Grant Manual Entitlement

Adds a manual entitlement grant for a (contact, feature). Useful for admin top-ups, comp credits, or migration. Idempotent on grantId.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Request Body

application/jsonRequired

contactIdRequiredstring

CRM contact id

featureKeyRequiredstring

Feature key

amountRequiredinteger

Units to grant

Minimum: 1Maximum: 9007199254740991

grantIdRequiredstring

Caller-supplied grant id for idempotency

metadataobject

Metadata applied if the entitlement record is being created (first grant).

POST/v1/entitlements/grants

curl -X POST "https://api.3common.com/v1/entitlements/grants" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "string",
    "featureKey": "string",
    "amount": 1,
    "grantId": "string",
    "metadata": {
      "property1": "string",
      "property2": "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;
  };
}