Grant promotional entitlement

POST

api

product_catalogues

promotional-entitlements

{id}

apply

cURL

curl -X POST https://api.metrifox.com/api/v1/product_catalogues/promotional-entitlements/625f5cee-259b-4994-b7eb-416b9e551f2c/apply \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "apply_to": "specific",
    "customer_keys": ["cust_001", "cust_002"]
  }'

{
  "statusCode": 201,
  "message": "Promotional entitlement applied",
  "meta": {},
  "data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "customer_id": "f4a2f74c-661b-428c-87f8-75cc1aa19c4c",
      "customer_key": "cust_001",
      "customer_name": "Acme Inc",
      "customer_email": "billing@acme.test",
      "active": true,
      "applied_at": "2026-06-01T10:00:00Z",
      "revoked_at": null,
      "created_at": "2026-06-01T10:00:00Z"
    }
  ],
  "errors": {}
}

Customers are identified by their customer_key. Use apply_to: "specific" with a customer_keys array to grant to a chosen set of customers, or apply_to: "all" to grant to every customer in your account.

A customer can hold only one active promotional entitlement per feature at a time. Granting to a specific customer who already has an active promo for the same feature is rejected; granting to all silently skips those customers.

Create and manage promotional entitlements (the templates being granted here) from the Metrifox dashboard. This endpoint grants an existing promotional entitlement, identified by its id, to your customers.

Authorizations

x-api-key

string

header

required

Path Parameters

string<uuid>

required

The unique identifier of the promotional entitlement to grant

Body

application/json

apply_to

enum<string>

default:specific

specific grants only to the customers listed in customer_keys. all grants to every customer in your account (and customer_keys is ignored).

Available options:

specific,

all

Example:

"specific"

customer_keys

string[]

The customer keys to grant the promotional entitlement to. Required when apply_to is specific.

Example:

["cust_001", "cust_002"]

Response

Promotional entitlement granted

statusCode

integer

Example:

201

message

string

Example:

"Promotional entitlement applied"

Documentation Index

Authorizations

Path Parameters

Body

Response