Skip to content
EntitlerDocs

PUT/v1/customers/{external_id}/spending-caps/{feature_key}

Set a spending cap

Sets or clears the customer's spending cap on a feature's overage: amount in the customer's currency's stored unit, or none to clear it. Usage that would take the overage past the cap is denied SPENDING_CAP_REACHED until the next period. Requires idempotencyKey; productId is optional. Needs customers:write or billing:self.

curl -X PUT 'https://api.entitler.co/v1/customers/ada/spending-caps/priority_support' \
  -H "Authorization: Bearer $ENTITLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1,"currency":"currency","expectedRevision":{"value":1},"idempotencyKey":"idempotencyKey","productId":"productId","reason":"reason","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.
feature_keyrequiredstring

Request body

object

  • amountinteger

    at least 0; at most 18446744073709552000

  • currencystring
  • expectedRevisioncommon.Revision-Input
    • valueinteger

      at least 0; at most 18446744073709552000

  • idempotencyKeystring
  • productIdstring
  • reasonstring
  • targetProductTarget
    • environmentIdstring
    • projectIdstring
    • teamIdstring

Responses

200The SetSpendingCapResponse message.

SetSpendingCapResponse

  • resultChangeResult
    • 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

        • modeModerequired

          One of MODE_UNSPECIFIED, MODE_LIVE, MODE_TEST.

        • periodIdstring
        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • priceLockedUntilinteger

          at least 0; at most 18446744073709552000

        • purchaseSourcestring
        • versionNumberintegerrequired

          at least 0; at most 18446744073709552000

      • productIdstring
      • quantityinteger (int64)

        at least 0; at most 4294967295

      • typePlanChangeTyperequired

        One of PLAN_CHANGE_TYPE_UNSPECIFIED, PLAN_CHANGE_TYPE_UPGRADE, PLAN_CHANGE_TYPE_DOWNGRADE, PLAN_CHANGE_TYPE_CROSSGRADE, PLAN_CHANGE_TYPE_LONGER_PERIOD, PLAN_CHANGE_TYPE_SHORTER_PERIOD.

      • 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
        • enabledboolean
        • limitcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
    • modeModerequired

      One of MODE_UNSPECIFIED, MODE_LIVE, MODE_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

        • modeModerequired

          One of MODE_UNSPECIFIED, MODE_LIVE, MODE_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

      • collectionMethodCollectionMethodrequired

        One of COLLECTION_METHOD_UNSPECIFIED, COLLECTION_METHOD_PAYMENT_PROVIDER, COLLECTION_METHOD_MANUAL, COLLECTION_METHOD_COMPLIMENTARY.

      • contractStartedAtinteger

        at least 0; at most 18446744073709552000

      • contractTermContractTerm
        • afterTermAfterTermrequired

          One of AFTER_TERM_UNSPECIFIED, AFTER_TERM_RENEW, AFTER_TERM_ROLLING, AFTER_TERM_END.

        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

      • coolingOffEndsAtinteger

        at least 0; at most 18446744073709552000

      • discountsarray of AppliedDiscountrequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • appliedbooleanrequired
        • appliedAtintegerrequired

          at least 0; at most 18446744073709552000

        • feesarray of OfferFeerequired
          • feeKeystringrequired
          • planIdstringrequired
        • minimumTermMonthsinteger (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
        • sourceDiscountSourcerequired

          One of DISCOUNT_SOURCE_UNSPECIFIED, DISCOUNT_SOURCE_BUSINESS, DISCOUNT_SOURCE_CUSTOMER, DISCOUNT_SOURCE_CODE, DISCOUNT_SOURCE_SEGMENT, DISCOUNT_SOURCE_REFERRAL.

        • startsAtinteger

          at least 0; at most 18446744073709552000

        • untilinteger

          at least 0; at most 18446744073709552000

        • usagePricesarray of OfferUsagePricerequired
          • planIdstringrequired
          • usagePriceKeystringrequired
      • 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

        • modeModerequired

          One of MODE_UNSPECIFIED, MODE_LIVE, MODE_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

      • spendingCapsarray of SpendingCaprequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • featureKeystringrequired
      • 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

        • modeModerequired

          One of MODE_UNSPECIFIED, MODE_LIVE, MODE_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

      • collectionMethodCollectionMethodrequired

        One of COLLECTION_METHOD_UNSPECIFIED, COLLECTION_METHOD_PAYMENT_PROVIDER, COLLECTION_METHOD_MANUAL, COLLECTION_METHOD_COMPLIMENTARY.

      • contractStartedAtinteger

        at least 0; at most 18446744073709552000

      • contractTermContractTerm
        • afterTermAfterTermrequired

          One of AFTER_TERM_UNSPECIFIED, AFTER_TERM_RENEW, AFTER_TERM_ROLLING, AFTER_TERM_END.

        • endsAtintegerrequired

          at least 0; at most 18446744073709552000

      • coolingOffEndsAtinteger

        at least 0; at most 18446744073709552000

      • discountsarray of AppliedDiscountrequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • appliedbooleanrequired
        • appliedAtintegerrequired

          at least 0; at most 18446744073709552000

        • feesarray of OfferFeerequired
          • feeKeystringrequired
          • planIdstringrequired
        • minimumTermMonthsinteger (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
        • sourceDiscountSourcerequired

          One of DISCOUNT_SOURCE_UNSPECIFIED, DISCOUNT_SOURCE_BUSINESS, DISCOUNT_SOURCE_CUSTOMER, DISCOUNT_SOURCE_CODE, DISCOUNT_SOURCE_SEGMENT, DISCOUNT_SOURCE_REFERRAL.

        • startsAtinteger

          at least 0; at most 18446744073709552000

        • untilinteger

          at least 0; at most 18446744073709552000

        • usagePricesarray of OfferUsagePricerequired
          • planIdstringrequired
          • usagePriceKeystringrequired
      • 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

        • modeModerequired

          One of MODE_UNSPECIFIED, MODE_LIVE, MODE_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

      • spendingCapsarray of SpendingCaprequired
        • amountAmount
          • amountintegerrequired

            at least 0; at most 18446744073709552000

          • currencystringrequired
          • displaystringrequired
        • featureKeystringrequired
      • 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

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

Error

  • errorobjectrequired
    • codestringrequired
    • parametersobjectrequired

      Each value: string

    • reasonstringor nullrequired