Skip to content
EntitlerDocs

POST/v1/customers/{external_id}/subscription:redeemOffer

Redeem an offer

Lets a customer redeem an offer by offer.offerKey or offer.code. Requires idempotencyKey; productId is optional. Needs customers:write or billing:self.

curl -X POST 'https://api.entitler.co/v1/customers/ada/subscription:redeemOffer' \
  -H "Authorization: Bearer $ENTITLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":{"value":1},"idempotencyKey":"idempotencyKey","offer":{"code":"code","offerKey":"offerKey"},"productId":"productId","reason":"reason","returnUrl":"returnUrl","target":{"environmentId":"environmentId","projectId":"projectId","teamId":"teamId"}}'

Credentials

Send any one of these:

  • Bearer token

Path parameters

NameTypeDescription
external_idrequiredstringThe customer's external ID, or me for the customer a customer token or identity token names.

Request body

object

  • expectedRevisioncommon.Revision-Input
    • valueinteger

      at least 0; at most 18446744073709552000

  • idempotencyKeystring
  • offerOfferRedemption
    • codestring
    • offerKeystring
  • productIdstring
  • reasonstring
  • returnUrlstring
  • targetProductTarget
    • environmentIdstring
    • projectIdstring
    • teamIdstring

Responses

200The RedeemOfferResponse message.

RedeemOfferResponse

  • completedChangeResult
    • changePlanChange
      • atintegerrequired

        at least 0; at most 18446744073709552000

      • changedbooleanrequired
      • effectiveEffectiverequired

        One of EFFECTIVE_UNSPECIFIED, EFFECTIVE_NOW, EFFECTIVE_RENEWAL.

      • planSubscriptionPlan
        • billingConnectionIdstring
        • cohortIdstring
        • cohortNumberinteger

          at least 0; at most 18446744073709552000

        • moneyCustomerMoneyrequired

          One of CUSTOMER_MONEY_UNSPECIFIED, CUSTOMER_MONEY_REAL, CUSTOMER_MONEY_TEST.

        • periodIdstring
        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • priceLockedUntilinteger

          at least 0; at most 18446744073709552000

        • purchaseSourcestring
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • policySubscriptionMovePolicyrequired

        One of SUBSCRIPTION_MOVE_POLICY_UNSPECIFIED, SUBSCRIPTION_MOVE_POLICY_UPGRADE, SUBSCRIPTION_MOVE_POLICY_DOWNGRADE, SUBSCRIPTION_MOVE_POLICY_CROSSGRADE, SUBSCRIPTION_MOVE_POLICY_LONGER, SUBSCRIPTION_MOVE_POLICY_SHORTER.

      • productIdstring
      • quantityinteger (int64)

        at least 0; at most 4294967295

      • untilinteger

        at least 0; at most 18446744073709552000

    • customerIdstringrequired
    • grantsarray of Grantrequired
      • featureKeystringrequired
      • fromintegerrequired

        at least 0; at most 18446744073709552000

      • grantedBycommon.Actor
        • idstringrequired
        • typecommon.ActorTyperequired

          One of ACTOR_TYPE_UNSPECIFIED, ACTOR_TYPE_USER, ACTOR_TYPE_KEY, ACTOR_TYPE_SYSTEM.

      • idstringrequired
      • reasonstringrequired
      • revokeReasonstring
      • revokedAtinteger

        at least 0; at most 18446744073709552000

      • revokedBycommon.Actor
        • idstringrequired
        • typecommon.ActorTyperequired

          One of ACTOR_TYPE_UNSPECIFIED, ACTOR_TYPE_USER, ACTOR_TYPE_KEY, ACTOR_TYPE_SYSTEM.

      • untilinteger

        at least 0; at most 18446744073709552000

      • valueGrantValue
        • limitcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • onSwitchOn
    • moneyCustomerMoneyrequired

      One of CUSTOMER_MONEY_UNSPECIFIED, CUSTOMER_MONEY_REAL, CUSTOMER_MONEY_TEST.

    • overLimitsarray of OverLimitrequired
      • featureKeystringrequired
      • kindOverLimitKindrequired

        One of OVER_LIMIT_KIND_UNSPECIFIED, OVER_LIMIT_KIND_FEATURE, OVER_LIMIT_KIND_MEMBERS.

      • limitintegerrequired

        at least 0; at most 18446744073709552000

      • usedintegerrequired

        at least 0; at most 18446744073709552000

    • revisionintegerrequired

      at least 0; at most 18446744073709552000

    • subscriptionSubscription
      • addOnsarray of SubscriptionAddOnrequired
        • addedAtintegerrequired

          at least 0; at most 18446744073709552000

        • billingConnectionIdstring
        • cohortIdstring
        • cohortNumberinteger

          at least 0; at most 18446744073709552000

        • moneyCustomerMoneyrequired

          One of CUSTOMER_MONEY_UNSPECIFIED, CUSTOMER_MONEY_REAL, CUSTOMER_MONEY_TEST.

        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • priceLockedUntilinteger

          at least 0; at most 18446744073709552000

        • purchaseSourcestring
        • quantityinteger (int64)required

          at least 0; at most 4294967295

        • requiredbooleanrequired
        • scheduledPlanIdstring
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • amountDueAmount
        • amountintegerrequired

          at least 0; at most 18446744073709552000

        • currencystringrequired
        • displaystringrequired
      • amountOverdueAmount
        • amountintegerrequired

          at least 0; at most 18446744073709552000

        • currencystringrequired
        • displaystringrequired
      • billedBilledPlan
        • billingConnectionIdstring
        • cohortIdstring
        • periodIdstring
        • planIdstringrequired
        • sinceintegerrequired

          at least 0; at most 18446744073709552000

        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • billingSubscriptionBillingrequired

        One of SUBSCRIPTION_BILLING_UNSPECIFIED, SUBSCRIPTION_BILLING_RECURRING, SUBSCRIPTION_BILLING_ONE_TIME.

      • cancellationCancellation
        • discountClawbackAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • earlyTerminationFeeAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

      • cancelsAtinteger

        at least 0; at most 18446744073709552000

      • collectionSubscriptionCollectionrequired

        One of SUBSCRIPTION_COLLECTION_UNSPECIFIED, SUBSCRIPTION_COLLECTION_PROVIDER, SUBSCRIPTION_COLLECTION_BUSINESS, SUBSCRIPTION_COLLECTION_NOT_CHARGED.

      • contractStartedAtinteger

        at least 0; at most 18446744073709552000

      • contractTermContractTerm
        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

        • thenTermThenrequired

          One of TERM_THEN_UNSPECIFIED, TERM_THEN_RENEW, TERM_THEN_ROLLING, TERM_THEN_END.

      • coolingOffEndsAtinteger

        at least 0; at most 18446744073709552000

      • discountsarray of AppliedDiscountrequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • appliedbooleanrequired
        • feesarray of OfferFeerequired
          • feeKeystringrequired
          • planIdstringrequired
        • givenAtintegerrequired

          at least 0; at most 18446744073709552000

        • givenByDiscountGivenByrequired

          One of DISCOUNT_GIVEN_BY_UNSPECIFIED, DISCOUNT_GIVEN_BY_BUSINESS, DISCOUNT_GIVEN_BY_CUSTOMER, DISCOUNT_GIVEN_BY_CODE, DISCOUNT_GIVEN_BY_SEGMENT, DISCOUNT_GIVEN_BY_REFERRAL.

        • minimumStayMonthsinteger (int64)

          at least 0; at most 4294967295

        • offerIdstringrequired
        • offerKeystringrequired
        • offerNamestringrequired
        • payerIdstring
        • percentThousandthsinteger (int64)

          at least 0; at most 4294967295

        • periodIdsarray of stringrequired
        • periodsLeftinteger (int64)

          at least 0; at most 4294967295

        • planIdsarray of stringrequired
        • startsAtinteger

          at least 0; at most 18446744073709552000

        • untilinteger

          at least 0; at most 18446744073709552000

      • instalmentsInstalmentPlan
        • amountLeftAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • paidinteger (int64)required

          at least 0; at most 4294967295

        • totalinteger (int64)required

          at least 0; at most 4294967295

      • onDefaultPlanbooleanrequired
      • overduePeriodsinteger (int64)required

        at least 0; at most 4294967295

      • paidOffAtinteger

        at least 0; at most 18446744073709552000

      • paidUntilinteger

        at least 0; at most 18446744073709552000

      • pausePause
        • daysLeftThisYearinteger (int64)

          at least 0; at most 4294967295

        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

        • startedAtintegerrequired

          at least 0; at most 18446744073709552000

      • payersarray of SubscriptionPayerrequired
        • addedAtintegerrequired

          at least 0; at most 18446744073709552000

        • customerIdstringrequired
        • endsAtinteger

          at least 0; at most 18446744073709552000

        • externalIdstringrequired
        • offerKeysarray of stringrequired
        • payerIdstringrequired
        • sharePayerShare
          • amountAmount
            • amountintegerrequired

              at least 0; at most 18446744073709552000

            • currencystringrequired
            • displaystringrequired
          • percentThousandthsinteger (int64)

            at least 0; at most 4294967295

        • startsAtinteger

          at least 0; at most 18446744073709552000

        • untilinteger

          at least 0; at most 18446744073709552000

      • paymentDueAtinteger

        at least 0; at most 18446744073709552000

      • paymentTermsPaymentTerms
        • daysUntilDueinteger (int64)required

          at least 0; at most 4294967295

        • suspensionSuspension
          • periodsWhileSuspendedPeriodsWhileSuspendedrequired

            One of PERIODS_WHILE_SUSPENDED_UNSPECIFIED, PERIODS_WHILE_SUSPENDED_STOP, PERIODS_WHILE_SUSPENDED_CONTINUE.

          • suspendAfterDaysinteger (int64)required

            at least 0; at most 4294967295

      • planSubscriptionPlan
        • billingConnectionIdstring
        • cohortIdstring
        • cohortNumberinteger

          at least 0; at most 18446744073709552000

        • moneyCustomerMoneyrequired

          One of CUSTOMER_MONEY_UNSPECIFIED, CUSTOMER_MONEY_REAL, CUSTOMER_MONEY_TEST.

        • periodIdstring
        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • priceLockedUntilinteger

          at least 0; at most 18446744073709552000

        • purchaseSourcestring
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • prepaidPeriodsinteger (int64)required

        at least 0; at most 4294967295

      • productIdstring
      • renewsAtinteger

        at least 0; at most 18446744073709552000

      • scheduledChangeScheduledChange
        • atintegerrequired

          at least 0; at most 18446744073709552000

        • cancellationScheduledCancellation
        • planChangeScheduledPlanChange
          • periodIdstring
          • planIdstringrequired
          • startsNewContractbooleanrequired
          • untilinteger

            at least 0; at most 18446744073709552000

      • scheduledVersionChangesarray of ScheduledVersionChangerequired
        • acceptanceRequiredbooleanrequired
        • acceptedbooleanrequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • effectiveAtintegerrequired

          at least 0; at most 18446744073709552000

        • planIdstringrequired
        • rolloutIdstringrequired
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • startedAtinteger

        at least 0; at most 18446744073709552000

      • statusSubscriptionStatusrequired

        One of SUBSCRIPTION_STATUS_UNSPECIFIED, SUBSCRIPTION_STATUS_ACTIVE, SUBSCRIPTION_STATUS_TRIALING, SUBSCRIPTION_STATUS_INCOMPLETE, SUBSCRIPTION_STATUS_SUSPENDED, SUBSCRIPTION_STATUS_PAUSED, SUBSCRIPTION_STATUS_PAID_OFF.

      • suspendedAtinteger

        at least 0; at most 18446744073709552000

      • suspensionEndsAtinteger

        at least 0; at most 18446744073709552000

      • trialTrial
        • convertedAtinteger

          at least 0; at most 18446744073709552000

        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

        • fallsBackToPlanIdstring
      • trialEndsAtinteger

        at least 0; at most 18446744073709552000

      • untilinteger

        at least 0; at most 18446744073709552000

    • subscriptionsarray of Subscriptionrequired
      • addOnsarray of SubscriptionAddOnrequired
        • addedAtintegerrequired

          at least 0; at most 18446744073709552000

        • billingConnectionIdstring
        • cohortIdstring
        • cohortNumberinteger

          at least 0; at most 18446744073709552000

        • moneyCustomerMoneyrequired

          One of CUSTOMER_MONEY_UNSPECIFIED, CUSTOMER_MONEY_REAL, CUSTOMER_MONEY_TEST.

        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • priceLockedUntilinteger

          at least 0; at most 18446744073709552000

        • purchaseSourcestring
        • quantityinteger (int64)required

          at least 0; at most 4294967295

        • requiredbooleanrequired
        • scheduledPlanIdstring
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • amountDueAmount
        • amountintegerrequired

          at least 0; at most 18446744073709552000

        • currencystringrequired
        • displaystringrequired
      • amountOverdueAmount
        • amountintegerrequired

          at least 0; at most 18446744073709552000

        • currencystringrequired
        • displaystringrequired
      • billedBilledPlan
        • billingConnectionIdstring
        • cohortIdstring
        • periodIdstring
        • planIdstringrequired
        • sinceintegerrequired

          at least 0; at most 18446744073709552000

        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • billingSubscriptionBillingrequired

        One of SUBSCRIPTION_BILLING_UNSPECIFIED, SUBSCRIPTION_BILLING_RECURRING, SUBSCRIPTION_BILLING_ONE_TIME.

      • cancellationCancellation
        • discountClawbackAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • earlyTerminationFeeAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

      • cancelsAtinteger

        at least 0; at most 18446744073709552000

      • collectionSubscriptionCollectionrequired

        One of SUBSCRIPTION_COLLECTION_UNSPECIFIED, SUBSCRIPTION_COLLECTION_PROVIDER, SUBSCRIPTION_COLLECTION_BUSINESS, SUBSCRIPTION_COLLECTION_NOT_CHARGED.

      • contractStartedAtinteger

        at least 0; at most 18446744073709552000

      • contractTermContractTerm
        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

        • thenTermThenrequired

          One of TERM_THEN_UNSPECIFIED, TERM_THEN_RENEW, TERM_THEN_ROLLING, TERM_THEN_END.

      • coolingOffEndsAtinteger

        at least 0; at most 18446744073709552000

      • discountsarray of AppliedDiscountrequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • appliedbooleanrequired
        • feesarray of OfferFeerequired
          • feeKeystringrequired
          • planIdstringrequired
        • givenAtintegerrequired

          at least 0; at most 18446744073709552000

        • givenByDiscountGivenByrequired

          One of DISCOUNT_GIVEN_BY_UNSPECIFIED, DISCOUNT_GIVEN_BY_BUSINESS, DISCOUNT_GIVEN_BY_CUSTOMER, DISCOUNT_GIVEN_BY_CODE, DISCOUNT_GIVEN_BY_SEGMENT, DISCOUNT_GIVEN_BY_REFERRAL.

        • minimumStayMonthsinteger (int64)

          at least 0; at most 4294967295

        • offerIdstringrequired
        • offerKeystringrequired
        • offerNamestringrequired
        • payerIdstring
        • percentThousandthsinteger (int64)

          at least 0; at most 4294967295

        • periodIdsarray of stringrequired
        • periodsLeftinteger (int64)

          at least 0; at most 4294967295

        • planIdsarray of stringrequired
        • startsAtinteger

          at least 0; at most 18446744073709552000

        • untilinteger

          at least 0; at most 18446744073709552000

      • instalmentsInstalmentPlan
        • amountLeftAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • paidinteger (int64)required

          at least 0; at most 4294967295

        • totalinteger (int64)required

          at least 0; at most 4294967295

      • onDefaultPlanbooleanrequired
      • overduePeriodsinteger (int64)required

        at least 0; at most 4294967295

      • paidOffAtinteger

        at least 0; at most 18446744073709552000

      • paidUntilinteger

        at least 0; at most 18446744073709552000

      • pausePause
        • daysLeftThisYearinteger (int64)

          at least 0; at most 4294967295

        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

        • startedAtintegerrequired

          at least 0; at most 18446744073709552000

      • payersarray of SubscriptionPayerrequired
        • addedAtintegerrequired

          at least 0; at most 18446744073709552000

        • customerIdstringrequired
        • endsAtinteger

          at least 0; at most 18446744073709552000

        • externalIdstringrequired
        • offerKeysarray of stringrequired
        • payerIdstringrequired
        • sharePayerShare
          • amountAmount
            • amountintegerrequired

              at least 0; at most 18446744073709552000

            • currencystringrequired
            • displaystringrequired
          • percentThousandthsinteger (int64)

            at least 0; at most 4294967295

        • startsAtinteger

          at least 0; at most 18446744073709552000

        • untilinteger

          at least 0; at most 18446744073709552000

      • paymentDueAtinteger

        at least 0; at most 18446744073709552000

      • paymentTermsPaymentTerms
        • daysUntilDueinteger (int64)required

          at least 0; at most 4294967295

        • suspensionSuspension
          • periodsWhileSuspendedPeriodsWhileSuspendedrequired

            One of PERIODS_WHILE_SUSPENDED_UNSPECIFIED, PERIODS_WHILE_SUSPENDED_STOP, PERIODS_WHILE_SUSPENDED_CONTINUE.

          • suspendAfterDaysinteger (int64)required

            at least 0; at most 4294967295

      • planSubscriptionPlan
        • billingConnectionIdstring
        • cohortIdstring
        • cohortNumberinteger

          at least 0; at most 18446744073709552000

        • moneyCustomerMoneyrequired

          One of CUSTOMER_MONEY_UNSPECIFIED, CUSTOMER_MONEY_REAL, CUSTOMER_MONEY_TEST.

        • periodIdstring
        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • priceLockedUntilinteger

          at least 0; at most 18446744073709552000

        • purchaseSourcestring
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • prepaidPeriodsinteger (int64)required

        at least 0; at most 4294967295

      • productIdstring
      • renewsAtinteger

        at least 0; at most 18446744073709552000

      • scheduledChangeScheduledChange
        • atintegerrequired

          at least 0; at most 18446744073709552000

        • cancellationScheduledCancellation
        • planChangeScheduledPlanChange
          • periodIdstring
          • planIdstringrequired
          • startsNewContractbooleanrequired
          • untilinteger

            at least 0; at most 18446744073709552000

      • scheduledVersionChangesarray of ScheduledVersionChangerequired
        • acceptanceRequiredbooleanrequired
        • acceptedbooleanrequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • effectiveAtintegerrequired

          at least 0; at most 18446744073709552000

        • planIdstringrequired
        • rolloutIdstringrequired
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • startedAtinteger

        at least 0; at most 18446744073709552000

      • statusSubscriptionStatusrequired

        One of SUBSCRIPTION_STATUS_UNSPECIFIED, SUBSCRIPTION_STATUS_ACTIVE, SUBSCRIPTION_STATUS_TRIALING, SUBSCRIPTION_STATUS_INCOMPLETE, SUBSCRIPTION_STATUS_SUSPENDED, SUBSCRIPTION_STATUS_PAUSED, SUBSCRIPTION_STATUS_PAID_OFF.

      • suspendedAtinteger

        at least 0; at most 18446744073709552000

      • suspensionEndsAtinteger

        at least 0; at most 18446744073709552000

      • trialTrial
        • convertedAtinteger

          at least 0; at most 18446744073709552000

        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

        • fallsBackToPlanIdstring
      • trialEndsAtinteger

        at least 0; at most 18446744073709552000

      • untilinteger

        at least 0; at most 18446744073709552000

  • paymentProcessingPaymentProcessing
  • paymentRequiredPaymentRequired
    • statusPaymentRequiredStatusrequired

      One of PAYMENT_REQUIRED_STATUS_UNSPECIFIED, PAYMENT_REQUIRED_STATUS_CHECKOUT, PAYMENT_REQUIRED_STATUS_CONFIRMATION, PAYMENT_REQUIRED_STATUS_REQUIRES_ACTION, PAYMENT_REQUIRED_STATUS_DECLINED, PAYMENT_REQUIRED_STATUS_PENDING.

    • urlstringrequired

ErrorA refusal, with the HTTP status of its gRPC code.

Error

  • errorobjectrequired
    • codestringrequired
    • parametersobjectrequired

      Each value: string

    • reasonstringor nullrequired