> ## 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 credit
> Grant a promotional credit 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 eligible customer in your account.
Eligibility is wallet-based — only customers with a wallet in the linked credit system can be granted. When **Allow multiple grants** is disabled, a customer who already holds an active grant is skipped; when it is enabled, the same customer can be granted again.
Create and manage promotional credits (the campaigns being granted here) from the Metrifox dashboard. This endpoint grants an existing promotional credit, identified by its `id`, to your customers.
## OpenAPI
````yaml POST /api/v1/credit_systems/promotional-credits/{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/credit_systems/promotional-credits/{id}/apply:
post:
tags:
- Promotional Credits
summary: Grant a promotional credit to customers
description: >
Grants (applies) a promotional credit to one or more customers. A
promotional credit is a time-bound
credit allocation campaign tied to a credit system that gives customers
a **consumable balance** — useful for:
- **Marketing campaigns**: rewarding a set of customers with bonus
credits
- **Goodwill / retention**: crediting a customer's balance outside their
plan
- **Trials and pilots**: giving prospective customers credits to spend
before they subscribe
Eligibility is wallet-based — only customers with a wallet in the linked
credit system can be granted.
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 eligible customer in your account.
When **Allow multiple grants** is disabled on the promotional credit, a
customer who already holds an active
grant is skipped. When it is enabled, the same customer can receive the
grant again.
operationId: grantPromotionalCredit
parameters:
- name: id
in: path
required: true
description: The unique identifier of the promotional credit 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 eligible 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 credit to.
Required when `apply_to` is `specific`.
example:
- cust_001
- cust_002
responses:
'201':
description: Promotional credit granted
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 201
message:
type: string
example: Promotional credit applied
meta:
type: object
data:
type: array
items:
type: object
description: A promotional credit 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 credit 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 credit is not active, or a specified
customer is not eligible (no wallet) or already has an active grant
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: >-
Customer cust_001 already has an active grant for this
promotional credit
errors: {}
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Promotional credit 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/credit_systems/promotional-credits/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
````