List Entitlements

Lists entitlement balance records for the host. Filterable by contact, feature, or minimum balance. Sorted by most-recently-updated.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Query Parameters

pageinteger

Default: 0Minimum: 0Maximum: 9007199254740991

pageSizeinteger

Default: 20Minimum: 1Maximum: 100

contactIdstring

Filter by recipient contact id

featureKeystring

Filter by feature

minBalanceinteger

Only entitlements with balance >= this

Minimum: 0Maximum: 9007199254740991

fieldsstring

Comma-separated list of fields. Valid: id, hostId, contactId, featureKey, balance, totalGranted, totalConsumed, createdAt, updatedAt. Omit for all.

GET/v1/entitlements/

curl -X GET "https://api.3common.com/v1/entitlements/?contactId=string&featureKey=string&fields=string" \
  -H "Authorization: Bearer <token>"

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"
    }
  ],
  "hasMore": true
}

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;
  }[];
  hasMore: boolean;
}