List promotional entitlements

cURL

curl -X GET "https://api.metrifox.com/api/v1/product_catalogues/promotional-entitlements?status=active" \
  -H "x-api-key: your_api_key"

{
  "statusCode": 200,
  "message": "Promotional entitlements fetched",
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "next_page": null,
    "prev_page": null
  },
  "data": [
    {
      "id": "625f5cee-259b-4994-b7eb-416b9e551f2c",
      "name": "Summer Campaign Boost",
      "description": "Extra API calls for the summer promotion",
      "mode": "additive",
      "included_allowance": 1000,
      "included_allowance_reset_interval": "monthly",
      "included_allowance_reset_anchor": null,
      "starts_at": "2026-06-01T00:00:00Z",
      "expires_at": "2026-09-01T00:00:00Z",
      "duration_value": 3,
      "duration_unit": "month",
      "status": "active",
      "is_applied": true,
      "feature_id": "9c1f1d2e-0000-0000-0000-000000000010",
      "feature_name": "API Calls",
      "feature_type": "metered",
      "created_at": "2026-05-20T10:00:00Z",
      "updated_at": "2026-05-20T10:00:00Z"
    }
  ],
  "errors": {}
}

GET

api

product_catalogues

promotional-entitlements

cURL

curl -X GET "https://api.metrifox.com/api/v1/product_catalogues/promotional-entitlements?status=active" \
  -H "x-api-key: your_api_key"

{
  "statusCode": 200,
  "message": "Promotional entitlements fetched",
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "next_page": null,
    "prev_page": null
  },
  "data": [
    {
      "id": "625f5cee-259b-4994-b7eb-416b9e551f2c",
      "name": "Summer Campaign Boost",
      "description": "Extra API calls for the summer promotion",
      "mode": "additive",
      "included_allowance": 1000,
      "included_allowance_reset_interval": "monthly",
      "included_allowance_reset_anchor": null,
      "starts_at": "2026-06-01T00:00:00Z",
      "expires_at": "2026-09-01T00:00:00Z",
      "duration_value": 3,
      "duration_unit": "month",
      "status": "active",
      "is_applied": true,
      "feature_id": "9c1f1d2e-0000-0000-0000-000000000010",
      "feature_name": "API Calls",
      "feature_type": "metered",
      "created_at": "2026-05-20T10:00:00Z",
      "updated_at": "2026-05-20T10:00:00Z"
    }
  ],
  "errors": {}
}

Use this to find the id of the promotional entitlement you want to grant. Pass that id to the Grant promotional entitlement endpoint.

Filter by status (scheduled, active, expired, deactivated), by feature_id, or by search (matches the name). Results are paginated — see the meta object.

Authorizations

x-api-key

string

header

required

Query Parameters

feature_id

string<uuid>

Filter by the feature the promotional entitlement grants

status

enum<string>

Filter by lifecycle status

Available options:

scheduled,

active,

expired,

deactivated

string

Filter by promotional entitlement name

page

integer

default:1

The page of results to return

per_page

integer

default:25

Number of records per page

Response

Promotional entitlements

statusCode

integer

Example:

200

message

string

Example:

"Promotional entitlements fetched"

Documentation Index

Authorizations

Query Parameters

Response