Skip to content
EntitlerDocs

POST/v1/customers/{external_id}/usage/{usage_id}:cancel

Cancel usage

Cancels recorded usage, returning its amount to the meter. A repeat reports the cancellation again, and an unknown ID is refused. Needs customers:write.

curl -X POST 'https://api.entitler.co/v1/customers/ada/usage/<usage_id>:cancel' \
  -H "Authorization: Bearer $ENTITLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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.
usage_idrequiredstring

Request body

object

  • reasonstring
  • targetProductTarget
    • environmentIdstring
    • projectIdstring
    • teamIdstring

Responses

200The CancelUsageResponse message.

CancelUsageResponse

  • resultUsageResult
    • asOfintegerrequired

      at least 0; at most 18446744073709552000

    • catalogueCustomerCatalogue
      • channelCatalogueChannel
        • idstringrequired
        • namestringrequired
      • draftIdstring
      • noneNoCatalogue
      • releaseCatalogueRelease
        • idstringrequired
        • numberintegerrequired

          at least 0; at most 18446744073709552000

    • customerEntitledCustomer
      • customerIdstring
      • externalIdstringrequired
    • entitlementEntitlement
      • coveragePercentThousandthsinteger (int64)

        at least 0; at most 4294967295

      • currencystringrequired
      • decimalsinteger (int64)required

        at least 0; at most 4294967295

      • entitledbooleanrequired
      • featureKeystringrequired
      • homeZonesarray of ZonedEntitlementrequired
        • entitledbooleanrequired
        • remainingcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • valuecommon.FeatureValue
          • enabledboolean
          • groupcommon.GroupValue
            • membersarray of common.GroupMemberrequired
              • coveragePercentThousandthsinteger (int64)

                at least 0; at most 4294967295

              • enabledboolean
              • featureKeystringrequired
              • groupcommon.GroupValue
              • meteredcommon.Limit
              • moneycommon.MarketLimits
              • settingcommon.SettingValue
              • waitingPeriodcommon.WaitingPeriod
          • meteredcommon.Limit
            • countinteger

              at least 0; at most 18446744073709552000

            • unlimitedcommon.Unlimited
          • moneycommon.MarketLimits
            • limitsarray of common.MarketLimitrequired
              • limitcommon.Limit
              • marketIdstringrequired
          • settingcommon.SettingValue
            • choicestring
            • numbercommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • textstring
        • zonestringrequired
      • hoursEntitledHours
        • closesAtinteger

          at least 0; at most 18446744073709552000

        • opensAtinteger

          at least 0; at most 18446744073709552000

        • withinAccessHoursbooleanrequired
      • kindEntitledFeatureKindrequired

        One of ENTITLED_FEATURE_KIND_UNSPECIFIED, ENTITLED_FEATURE_KIND_BOOLEAN, ENTITLED_FEATURE_KIND_METERED, ENTITLED_FEATURE_KIND_SETTING, ENTITLED_FEATURE_KIND_GROUP.

      • memberMeterMeter
        • remainingcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • reservedintegerrequired

          at least 0; at most 18446744073709552000

        • resetsAtinteger

          at least 0; at most 18446744073709552000

        • rolledOverintegerrequired

          at least 0; at most 18446744073709552000

        • topUpLeftintegerrequired

          at least 0; at most 18446744073709552000

        • topUpSpentintegerrequired

          at least 0; at most 18446744073709552000

        • usedintegerrequired

          at least 0; at most 18446744073709552000

      • meterMeter
        • remainingcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • reservedintegerrequired

          at least 0; at most 18446744073709552000

        • resetsAtinteger

          at least 0; at most 18446744073709552000

        • rolledOverintegerrequired

          at least 0; at most 18446744073709552000

        • topUpLeftintegerrequired

          at least 0; at most 18446744073709552000

        • topUpSpentintegerrequired

          at least 0; at most 18446744073709552000

        • usedintegerrequired

          at least 0; at most 18446744073709552000

      • perMemberValuecommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • perUseLimitcommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • pooledBystring
      • pooledLimitcommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • sourcesarray of EntitlementSourcerequired
        • addOnAddOnSource
          • planIdstringrequired
          • planKeystringrequired
          • planNamestringrequired
          • quantityinteger (int64)required

            at least 0; at most 4294967295

          • throughFeatureKeystring
          • valuecommon.FeatureValue
            • enabledboolean
            • groupcommon.GroupValue
              • membersarray of common.GroupMemberrequired
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
          • versionNumberintegerrequired

            at least 0; at most 18446744073709552000

        • defaultPlanDefaultPlanSource
          • planIdstringrequired
          • planKeystringrequired
          • planNamestringrequired
          • productIdstring
          • throughFeatureKeystring
          • versionNumberintegerrequired

            at least 0; at most 18446744073709552000

        • grantGrantSource
          • grantIdstringrequired
          • throughFeatureKeystring
          • untilinteger

            at least 0; at most 18446744073709552000

          • valuecommon.FeatureValue
            • enabledboolean
            • groupcommon.GroupValue
              • membersarray of common.GroupMemberrequired
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
        • groupGroupSource
          • featureKeysarray of stringrequired
        • planPlanSource
          • planIdstringrequired
          • planKeystringrequired
          • planNamestringrequired
          • productIdstring
          • throughFeatureKeystring
          • valuecommon.FeatureValue
            • enabledboolean
            • groupcommon.GroupValue
              • membersarray of common.GroupMemberrequired
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
          • versionNumberintegerrequired

            at least 0; at most 18446744073709552000

        • segmentKeystring
      • uncountedZonesarray of stringrequired
      • upgradesarray of Upgraderequired
        • actionUpgradeActionrequired

          One of UPGRADE_ACTION_UNSPECIFIED, UPGRADE_ACTION_BUY, UPGRADE_ACTION_CONTACT.

        • kindUpgradeKindrequired

          One of UPGRADE_KIND_UNSPECIFIED, UPGRADE_KIND_PLAN, UPGRADE_KIND_ADD_ON.

        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • productIdstring
        • typeUpgradeTyperequired

          One of UPGRADE_TYPE_UNSPECIFIED, UPGRADE_TYPE_SUBSCRIBE, UPGRADE_TYPE_UPGRADE, UPGRADE_TYPE_CROSSGRADE, UPGRADE_TYPE_ADD, UPGRADE_TYPE_REPLACE.

      • valuecommon.FeatureValue
        • enabledboolean
        • groupcommon.GroupValue
          • membersarray of common.GroupMemberrequired
            • coveragePercentThousandthsinteger (int64)

              at least 0; at most 4294967295

            • enabledboolean
            • featureKeystringrequired
            • groupcommon.GroupValue
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
            • waitingPeriodcommon.WaitingPeriod
              • countinteger (int64)required

                at least 0; at most 4294967295

              • unitcommon.WaitingPeriodUnitrequired

                One of WAITING_PERIOD_UNIT_UNSPECIFIED, WAITING_PERIOD_UNIT_DAYS, WAITING_PERIOD_UNIT_MONTHS.

        • meteredcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • moneycommon.MarketLimits
          • limitsarray of common.MarketLimitrequired
            • limitcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • marketIdstringrequired
        • settingcommon.SettingValue
          • choicestring
          • numbercommon.Limit
            • countinteger

              at least 0; at most 18446744073709552000

            • unlimitedcommon.Unlimited
          • textstring
      • waitingUntilinteger

        at least 0; at most 18446744073709552000

    • memberEntitledMember
      • externalIdstringrequired
      • memberIdstringrequired
    • sharedEntitlement
      • coveragePercentThousandthsinteger (int64)

        at least 0; at most 4294967295

      • currencystringrequired
      • decimalsinteger (int64)required

        at least 0; at most 4294967295

      • entitledbooleanrequired
      • featureKeystringrequired
      • homeZonesarray of ZonedEntitlementrequired
        • entitledbooleanrequired
        • remainingcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • valuecommon.FeatureValue
          • enabledboolean
          • groupcommon.GroupValue
            • membersarray of common.GroupMemberrequired
              • coveragePercentThousandthsinteger (int64)

                at least 0; at most 4294967295

              • enabledboolean
              • featureKeystringrequired
              • groupcommon.GroupValue
              • meteredcommon.Limit
              • moneycommon.MarketLimits
              • settingcommon.SettingValue
              • waitingPeriodcommon.WaitingPeriod
          • meteredcommon.Limit
            • countinteger

              at least 0; at most 18446744073709552000

            • unlimitedcommon.Unlimited
          • moneycommon.MarketLimits
            • limitsarray of common.MarketLimitrequired
              • limitcommon.Limit
              • marketIdstringrequired
          • settingcommon.SettingValue
            • choicestring
            • numbercommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • textstring
        • zonestringrequired
      • hoursEntitledHours
        • closesAtinteger

          at least 0; at most 18446744073709552000

        • opensAtinteger

          at least 0; at most 18446744073709552000

        • withinAccessHoursbooleanrequired
      • kindEntitledFeatureKindrequired

        One of ENTITLED_FEATURE_KIND_UNSPECIFIED, ENTITLED_FEATURE_KIND_BOOLEAN, ENTITLED_FEATURE_KIND_METERED, ENTITLED_FEATURE_KIND_SETTING, ENTITLED_FEATURE_KIND_GROUP.

      • memberMeterMeter
        • remainingcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • reservedintegerrequired

          at least 0; at most 18446744073709552000

        • resetsAtinteger

          at least 0; at most 18446744073709552000

        • rolledOverintegerrequired

          at least 0; at most 18446744073709552000

        • topUpLeftintegerrequired

          at least 0; at most 18446744073709552000

        • topUpSpentintegerrequired

          at least 0; at most 18446744073709552000

        • usedintegerrequired

          at least 0; at most 18446744073709552000

      • meterMeter
        • remainingcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • reservedintegerrequired

          at least 0; at most 18446744073709552000

        • resetsAtinteger

          at least 0; at most 18446744073709552000

        • rolledOverintegerrequired

          at least 0; at most 18446744073709552000

        • topUpLeftintegerrequired

          at least 0; at most 18446744073709552000

        • topUpSpentintegerrequired

          at least 0; at most 18446744073709552000

        • usedintegerrequired

          at least 0; at most 18446744073709552000

      • perMemberValuecommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • perUseLimitcommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • pooledBystring
      • pooledLimitcommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • sourcesarray of EntitlementSourcerequired
        • addOnAddOnSource
          • planIdstringrequired
          • planKeystringrequired
          • planNamestringrequired
          • quantityinteger (int64)required

            at least 0; at most 4294967295

          • throughFeatureKeystring
          • valuecommon.FeatureValue
            • enabledboolean
            • groupcommon.GroupValue
              • membersarray of common.GroupMemberrequired
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
          • versionNumberintegerrequired

            at least 0; at most 18446744073709552000

        • defaultPlanDefaultPlanSource
          • planIdstringrequired
          • planKeystringrequired
          • planNamestringrequired
          • productIdstring
          • throughFeatureKeystring
          • versionNumberintegerrequired

            at least 0; at most 18446744073709552000

        • grantGrantSource
          • grantIdstringrequired
          • throughFeatureKeystring
          • untilinteger

            at least 0; at most 18446744073709552000

          • valuecommon.FeatureValue
            • enabledboolean
            • groupcommon.GroupValue
              • membersarray of common.GroupMemberrequired
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
        • groupGroupSource
          • featureKeysarray of stringrequired
        • planPlanSource
          • planIdstringrequired
          • planKeystringrequired
          • planNamestringrequired
          • productIdstring
          • throughFeatureKeystring
          • valuecommon.FeatureValue
            • enabledboolean
            • groupcommon.GroupValue
              • membersarray of common.GroupMemberrequired
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
          • versionNumberintegerrequired

            at least 0; at most 18446744073709552000

        • segmentKeystring
      • uncountedZonesarray of stringrequired
      • upgradesarray of Upgraderequired
        • actionUpgradeActionrequired

          One of UPGRADE_ACTION_UNSPECIFIED, UPGRADE_ACTION_BUY, UPGRADE_ACTION_CONTACT.

        • kindUpgradeKindrequired

          One of UPGRADE_KIND_UNSPECIFIED, UPGRADE_KIND_PLAN, UPGRADE_KIND_ADD_ON.

        • planIdstringrequired
        • planKeystringrequired
        • planNamestringrequired
        • productIdstring
        • typeUpgradeTyperequired

          One of UPGRADE_TYPE_UNSPECIFIED, UPGRADE_TYPE_SUBSCRIBE, UPGRADE_TYPE_UPGRADE, UPGRADE_TYPE_CROSSGRADE, UPGRADE_TYPE_ADD, UPGRADE_TYPE_REPLACE.

      • valuecommon.FeatureValue
        • enabledboolean
        • groupcommon.GroupValue
          • membersarray of common.GroupMemberrequired
            • coveragePercentThousandthsinteger (int64)

              at least 0; at most 4294967295

            • enabledboolean
            • featureKeystringrequired
            • groupcommon.GroupValue
            • meteredcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • moneycommon.MarketLimits
              • limitsarray of common.MarketLimitrequired
            • settingcommon.SettingValue
              • choicestring
              • numbercommon.Limit
              • textstring
            • waitingPeriodcommon.WaitingPeriod
              • countinteger (int64)required

                at least 0; at most 4294967295

              • unitcommon.WaitingPeriodUnitrequired

                One of WAITING_PERIOD_UNIT_UNSPECIFIED, WAITING_PERIOD_UNIT_DAYS, WAITING_PERIOD_UNIT_MONTHS.

        • meteredcommon.Limit
          • countinteger

            at least 0; at most 18446744073709552000

          • unlimitedcommon.Unlimited
        • moneycommon.MarketLimits
          • limitsarray of common.MarketLimitrequired
            • limitcommon.Limit
              • countinteger

                at least 0; at most 18446744073709552000

              • unlimitedcommon.Unlimited
            • marketIdstringrequired
        • settingcommon.SettingValue
          • choicestring
          • numbercommon.Limit
            • countinteger

              at least 0; at most 18446744073709552000

            • unlimitedcommon.Unlimited
          • textstring
      • waitingUntilinteger

        at least 0; at most 18446744073709552000

    • usageUsageOutcomeDetails
      • amountintegerrequired

        at least 0; at most 18446744073709552000

      • cappedbooleanrequired
      • cappedByCappedBy

        One of CAPPED_BY_UNSPECIFIED, CAPPED_BY_FEATURE, CAPPED_BY_MEMBER, CAPPED_BY_SHARED, CAPPED_BY_SHARED_MEMBER.

      • costinteger

        at least 0; at most 18446744073709552000

      • countedbooleanrequired
      • coveragePercentThousandthsinteger (int64)

        at least 0; at most 4294967295

      • denialReasonDenialReason

        One of DENIAL_REASON_UNSPECIFIED, DENIAL_REASON_NOT_ENTITLED, DENIAL_REASON_OVER_ALLOWANCE, DENIAL_REASON_NOT_COVERED, DENIAL_REASON_WAITING, DENIAL_REASON_OUTSIDE_HOURS, DENIAL_REASON_OVER_PER_USE, DENIAL_REASON_MEMBER_OVER_ALLOWANCE, DENIAL_REASON_SHARED_OVER_ALLOWANCE.

      • expiresAtMsinteger

        at least 0; at most 18446744073709552000

      • holdIdstring
      • latebooleanrequired
      • memberOverByintegerrequired

        at least 0; at most 18446744073709552000

      • meterChangeinteger (int64)required
      • modeUsageModerequired

        One of USAGE_MODE_UNSPECIFIED, USAGE_MODE_ENFORCE, USAGE_MODE_RECORD_ONLY.

      • occurredAtMsinteger

        at least 0; at most 18446744073709552000

      • opensAtinteger

        at least 0; at most 18446744073709552000

      • outcomeUsageOutcomerequired

        One of USAGE_OUTCOME_UNSPECIFIED, USAGE_OUTCOME_RECORDED, USAGE_OUTCOME_DENIED, USAGE_OUTCOME_DUPLICATE, USAGE_OUTCOME_CANCELLED, USAGE_OUTCOME_HELD, USAGE_OUTCOME_SETTLED, USAGE_OUTCOME_RELEASED, USAGE_OUTCOME_ADJUSTED.

      • overByintegerrequired

        at least 0; at most 18446744073709552000

      • perUseLimitcommon.Limit
        • countinteger

          at least 0; at most 18446744073709552000

        • unlimitedcommon.Unlimited
      • perUseOverByintegerrequired

        at least 0; at most 18446744073709552000

      • replayedbooleanrequired
      • saturatedbooleanrequired
      • sharedOverByintegerrequired

        at least 0; at most 18446744073709552000

      • usageIdstring
      • waitingUntilinteger

        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