> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grant promotional entitlement
> Grant a promotional entitlement to specific customers or to all customers
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.
## OpenAPI
````yaml POST /api/v1/product_catalogues/promotional-entitlements/{id}/apply
openapi: 3.0.1
info:
title: Metrifox API Documentation
version: v1
description: >-
Welcome to Metrifox Platform's API documentation. This comprehensive API
suite enables seamless integration with our platform, providing secure and
efficient access to our services.
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: api.metrifox.com
security:
- api_key: []
paths:
/api/v1/product_catalogues/promotional-entitlements/{id}/apply:
post:
tags:
- Promotional Entitlements
summary: Grant a promotional entitlement to customers
description: >
Grants (applies) a promotional entitlement to one or more customers. A
promotional entitlement is a
standalone grant of feature allowance that lives **outside** of a
subscription — useful for:
- **Marketing campaigns**: temporarily boosting a feature's allowance
for a set of customers
- **Goodwill / retention**: granting extra capacity to a customer
outside their plan
- **Trials and pilots**: giving prospective customers access to a
feature before they subscribe
Identify customers by their `customer_key`. Set `apply_to` to `specific`
and pass `customer_keys` to
grant to a chosen set of customers, or set `apply_to` to `all` to grant
to every customer in your account.
A customer can only hold **one active promotional entitlement per
feature** at a time. When granting to a
specific customer who already has an active promo for the same feature,
the request is rejected. When
granting to `all`, customers who already have an active promo for that
feature are silently skipped.
operationId: grantPromotionalEntitlement
parameters:
- name: id
in: path
required: true
description: The unique identifier of the promotional entitlement to grant
schema:
type: string
format: uuid
example: 625f5cee-259b-4994-b7eb-416b9e551f2c
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
apply_to:
type: string
enum:
- specific
- all
default: specific
description: >
`specific` grants only to the customers listed in
`customer_keys`.
`all` grants to every customer in your account (and
`customer_keys` is ignored).
example: specific
customer_keys:
type: array
items:
type: string
description: >-
The customer keys to grant the promotional entitlement to.
Required when `apply_to` is `specific`.
example:
- cust_001
- cust_002
responses:
'201':
description: Promotional entitlement granted
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 201
message:
type: string
example: Promotional entitlement applied
meta:
type: object
data:
type: array
items:
type: object
description: A promotional entitlement granted to a single customer.
properties:
id:
type: string
format: uuid
description: The unique identifier of the assignment
customer_id:
type: string
format: uuid
description: The internal Metrifox identifier of the customer
customer_key:
type: string
description: Your external identifier for the customer
customer_name:
type: string
description: The customer's display name
customer_email:
type: string
description: The customer's primary email
active:
type: boolean
description: >-
Whether the grant is currently active (false once
revoked)
applied_at:
type: string
format: date-time
nullable: true
description: >-
When the grant became active. Null for scheduled
promos that have not started yet.
revoked_at:
type: string
format: date-time
nullable: true
description: When the grant was revoked, if applicable
created_at:
type: string
format: date-time
description: When the assignment record was created
errors:
type: object
example:
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: {}
'400':
description: >-
Bad request — the promotional entitlement is not active, or a
specified customer already has an active promo for this feature
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: >-
Customer cust_001 already has an active promotional
entitlement for this feature
errors: {}
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Promotional entitlement or one or more customers not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 404
message: One or more customers not found
errors: {}
x-codeSamples:
- lang: curl
label: cURL
source: >
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"]
}'
components:
schemas:
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
errors:
type: object
additionalProperties: true
description: Detailed error information
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
````