POST/v1/customers/{external_id}/usage

Report usage

Records usage of a metered feature for the customer. Requires idempotencyKey; amount defaults to 1. A replay with the same key returns the original. register first registers a missing customer and needs customers:register or customers:write. Needs usage:write.

curl -X POST 'https://api.entitler.co/v1/customers/ada/usage' \
  -H "Authorization: Bearer $ENTITLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1,"createCustomer":true,"currency":"currency","featureKey":"featureKey","idempotencyKey":"idempotencyKey","memberId":"memberId","mode":"USAGE_MODE_UNSPECIFIED","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

amountinteger
at least 0; at most 18446744073709552000
createCustomerboolean
currencystring
featureKeystring
idempotencyKeystring
memberIdstring
modeUsageMode
One of USAGE_MODE_UNSPECIFIED, USAGE_MODE_GATE, USAGE_MODE_OBSERVE.
occurredAtMsinteger
at least 0; at most 18446744073709552000
targetProductTarget
- environmentIdstring
- projectIdstring
- teamIdstring
zonestring

Responses

`200`The ReportUsageResponse message.

ReportUsageResponse

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