POST/v1/customers/{external_id}/usage:claim

Claim a benefit

Reports what a service cost in the customer's currency and pays the benefit the customer's plans set, the whole cost when none sets one, rounded by the feature's rule and capped at what is left of the limit. Requires idempotencyKey; occurredAtMs is the date of service. Not available to customer tokens. Needs usage:write.

curl -X POST 'https://api.entitler.co/v1/customers/ada/usage:claim' \
  -H "Authorization: Bearer $ENTITLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cost":1,"currency":"currency","featureKey":"featureKey","idempotencyKey":"idempotencyKey","occurredAtMs":1,"target":{"environmentId":"environmentId","projectId":"projectId","teamId":"teamId"},"zone":"zone"}'

Credentials

Send any one of these:

Bearer token

Path parameters

Name	Type	Description
`external_id`required	string	The customer's external ID, or `me` for the customer a customer token or identity token names.

Request body

object

costinteger
at least 0; at most 18446744073709552000
currencystring
featureKeystring
idempotencyKeystring
occurredAtMsinteger
at least 0; at most 18446744073709552000
targetProductTarget
- environmentIdstring
- projectIdstring
- teamIdstring
zonestring

Responses

`200`The ClaimBenefitResponse message.

ClaimBenefitResponse

trackedTrackedUsage
- asOfintegerrequired
  at least 0; at most 18446744073709552000
- customerEntitledCustomer
  - customerIdstring
  - externalIdstringrequired
- entitlementEntitlement
  - benefitThousandthsinteger (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
      - groupcommon.GroupValue
        membersarray of common.GroupMemberrequired
        benefitThousandthsinteger (int64)
        at least 0; at most 4294967295
        featureKeystringrequired
        groupcommon.GroupValue
        meteredcommon.Limit
        moneycommon.MarketLimits
        settingcommon.SettingValue
        switchboolean
        waitcommon.Wait
      - 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
      - switchboolean
    - zonestringrequired
  - hoursEntitledHours
    - closesAtinteger
      at least 0; at most 18446744073709552000
    - openbooleanrequired
    - opensAtinteger
      at least 0; at most 18446744073709552000
  - kindEntitledFeatureKindrequired
    One of ENTITLED_FEATURE_KIND_UNSPECIFIED, ENTITLED_FEATURE_KIND_SWITCH, ENTITLED_FEATURE_KIND_METERED, ENTITLED_FEATURE_KIND_SETTING, ENTITLED_FEATURE_KIND_GROUP.
  - memberMeterMeter
    - bankedintegerrequired
      at least 0; at most 18446744073709552000
    - heldintegerrequired
      at least 0; at most 18446744073709552000
    - remainingcommon.Limit
      - countinteger
        at least 0; at most 18446744073709552000
      - unlimitedcommon.Unlimited
    - resetsAtinteger
      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
  - memberValuecommon.Limit
    - countinteger
      at least 0; at most 18446744073709552000
    - unlimitedcommon.Unlimited
  - meterMeter
    - bankedintegerrequired
      at least 0; at most 18446744073709552000
    - heldintegerrequired
      at least 0; at most 18446744073709552000
    - remainingcommon.Limit
      - countinteger
        at least 0; at most 18446744073709552000
      - unlimitedcommon.Unlimited
    - resetsAtinteger
      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
  - perUsecommon.Limit
    - countinteger
      at least 0; at most 18446744073709552000
    - unlimitedcommon.Unlimited
  - sharedBystring
  - sharedValuecommon.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
        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
        switchboolean
      - 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
        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
        switchboolean
    - groupGroupSource
      - featureKeysarray of stringrequired
    - planPlanSource
      - planIdstringrequired
      - planKeystringrequired
      - planNamestringrequired
      - productIdstring
      - throughFeatureKeystring
      - valuecommon.FeatureValue
        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
        switchboolean
      - 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.
    - moveUpgradeMoverequired
      One of UPGRADE_MOVE_UNSPECIFIED, UPGRADE_MOVE_SUBSCRIBE, UPGRADE_MOVE_UPGRADE, UPGRADE_MOVE_SWITCH, UPGRADE_MOVE_ADD, UPGRADE_MOVE_REPLACE.
    - planIdstringrequired
    - planKeystringrequired
    - planNamestringrequired
    - productIdstring
  - valuecommon.FeatureValue
    - groupcommon.GroupValue
      - membersarray of common.GroupMemberrequired
        benefitThousandthsinteger (int64)
        at least 0; at most 4294967295
        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
        switchboolean
        waitcommon.Wait
        countinteger (int64)required
        at least 0; at most 4294967295
        unitcommon.WaitUnitrequired
        One of WAIT_UNIT_UNSPECIFIED, WAIT_UNIT_DAYS, WAIT_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
    - switchboolean
  - waitingUntilinteger
    at least 0; at most 18446744073709552000
- memberEntitledMember
  - externalIdstringrequired
  - memberIdstringrequired
- servedServedCatalogue
  - changeIdstring
  - nothingNothingServed
  - releaseServedRelease
    - idstringrequired
    - numberintegerrequired
      at least 0; at most 18446744073709552000
  - trackServedTrack
    - idstringrequired
    - namestringrequired
- sharedEntitlement
  - benefitThousandthsinteger (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
      - groupcommon.GroupValue
        membersarray of common.GroupMemberrequired
        benefitThousandthsinteger (int64)
        at least 0; at most 4294967295
        featureKeystringrequired
        groupcommon.GroupValue
        meteredcommon.Limit
        moneycommon.MarketLimits
        settingcommon.SettingValue
        switchboolean
        waitcommon.Wait
      - 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
      - switchboolean
    - zonestringrequired
  - hoursEntitledHours
    - closesAtinteger
      at least 0; at most 18446744073709552000
    - openbooleanrequired
    - opensAtinteger
      at least 0; at most 18446744073709552000
  - kindEntitledFeatureKindrequired
    One of ENTITLED_FEATURE_KIND_UNSPECIFIED, ENTITLED_FEATURE_KIND_SWITCH, ENTITLED_FEATURE_KIND_METERED, ENTITLED_FEATURE_KIND_SETTING, ENTITLED_FEATURE_KIND_GROUP.
  - memberMeterMeter
    - bankedintegerrequired
      at least 0; at most 18446744073709552000
    - heldintegerrequired
      at least 0; at most 18446744073709552000
    - remainingcommon.Limit
      - countinteger
        at least 0; at most 18446744073709552000
      - unlimitedcommon.Unlimited
    - resetsAtinteger
      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
  - memberValuecommon.Limit
    - countinteger
      at least 0; at most 18446744073709552000
    - unlimitedcommon.Unlimited
  - meterMeter
    - bankedintegerrequired
      at least 0; at most 18446744073709552000
    - heldintegerrequired
      at least 0; at most 18446744073709552000
    - remainingcommon.Limit
      - countinteger
        at least 0; at most 18446744073709552000
      - unlimitedcommon.Unlimited
    - resetsAtinteger
      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
  - perUsecommon.Limit
    - countinteger
      at least 0; at most 18446744073709552000
    - unlimitedcommon.Unlimited
  - sharedBystring
  - sharedValuecommon.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
        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
        switchboolean
      - 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
        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
        switchboolean
    - groupGroupSource
      - featureKeysarray of stringrequired
    - planPlanSource
      - planIdstringrequired
      - planKeystringrequired
      - planNamestringrequired
      - productIdstring
      - throughFeatureKeystring
      - valuecommon.FeatureValue
        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
        switchboolean
      - 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.
    - moveUpgradeMoverequired
      One of UPGRADE_MOVE_UNSPECIFIED, UPGRADE_MOVE_SUBSCRIBE, UPGRADE_MOVE_UPGRADE, UPGRADE_MOVE_SWITCH, UPGRADE_MOVE_ADD, UPGRADE_MOVE_REPLACE.
    - planIdstringrequired
    - planKeystringrequired
    - planNamestringrequired
    - productIdstring
  - valuecommon.FeatureValue
    - groupcommon.GroupValue
      - membersarray of common.GroupMemberrequired
        benefitThousandthsinteger (int64)
        at least 0; at most 4294967295
        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
        switchboolean
        waitcommon.Wait
        countinteger (int64)required
        at least 0; at most 4294967295
        unitcommon.WaitUnitrequired
        One of WAIT_UNIT_UNSPECIFIED, WAIT_UNIT_DAYS, WAIT_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
    - switchboolean
  - waitingUntilinteger
    at least 0; at most 18446744073709552000
- usageUsageResult
  - amountintegerrequired
    at least 0; at most 18446744073709552000
  - benefitThousandthsinteger (int64)
    at least 0; at most 4294967295
  - 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
  - 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_GATE, USAGE_MODE_OBSERVE.
  - 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_REFUSED, 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
  - perUsecommon.Limit
    - countinteger
      at least 0; at most 18446744073709552000
    - unlimitedcommon.Unlimited
  - perUseOverByintegerrequired
    at least 0; at most 18446744073709552000
  - refusalUsageRefusal
    One of USAGE_REFUSAL_UNSPECIFIED, USAGE_REFUSAL_NOT_ENTITLED, USAGE_REFUSAL_OVER_ALLOWANCE, USAGE_REFUSAL_NO_BENEFIT, USAGE_REFUSAL_WAITING, USAGE_REFUSAL_OUTSIDE_HOURS, USAGE_REFUSAL_OVER_PER_USE, USAGE_REFUSAL_MEMBER_OVER_ALLOWANCE, USAGE_REFUSAL_SHARED_OVER_ALLOWANCE.
  - replayedbooleanrequired
  - saturatedbooleanrequired
  - sharedOverByintegerrequired
    at least 0; at most 18446744073709552000
  - usageIdstring
  - waitingUntilinteger
    at least 0; at most 18446744073709552000

`Error`A refusal, with the HTTP status of its gRPC code.

Error

errorobjectrequired
- codestringrequired
- parametersobjectrequired
  Each value: string
- reasonstringor nullrequired