Consume Entitlement

Debits units from a customer's entitlement balance. Throws on insufficient balance. Debits one_time_addon grants first, then manual, then subscription_recurring (FIFO within source).

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Request Body

application/jsonRequired

contactIdRequiredstring

CRM contact id

featureKeyRequiredstring

Feature key

amountRequiredinteger

Units to consume

Minimum: 1Maximum: 9007199254740991

reasonstring

Free-form reason logged on the consumed event

POST/v1/entitlements/consume

curl -X POST "https://api.3common.com/v1/entitlements/consume" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "string",
    "featureKey": "string",
    "amount": 1,
    "reason": "string"
  }'

Default Response

Response

{
  "data": {
    "id": "string",
    "hostId": "string",
    "contactId": "string",
    "featureKey": "string",
    "balance": 9007199254740991,
    "grants": [
      {
        "id": "string",
        "source": "subscription_recurring",
        "sourceId": "string",
        "priceId": "string",
        "amount": 1,
        "remaining": 9007199254740991,
        "addedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "totalGranted": 9007199254740991,
    "totalConsumed": 9007199254740991,
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

TypeScript

export interface Response {
  data: {
    id?: string;
    hostId?: string;
    contactId?: string;
    featureKey?: string;
    balance?: number;
    grants?: {
      id: string;
      /**
       * Source of an entitlement grant.
       * - subscription_recurring: cycle grant from a subscription renewal
       * - one_time_addon: top-up purchase (consumed first by ConsumeEntitlement)
       * - manual: admin-applied grant
       */
      source: "subscription_recurring" | "one_time_addon" | "manual";
      sourceId?: string;
      priceId?: string;
      amount: number;
      remaining: number;
      addedAt: string;
    }[];
    totalGranted?: number;
    totalConsumed?: number;
    metadata?: {
      [k: string]: string;
    };
    createdAt?: string;
    updatedAt?: string;
  };
}