Grant promotional credit

POST

api

credit_systems

promotional-credits

{id}

apply

cURL

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"]
  }'

{
  "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": {}
}

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.

Authorizations

x-api-key

string

header

required

Path Parameters

string<uuid>

required

The unique identifier of the promotional credit 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 eligible 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 credit to. Required when apply_to is specific.

Example:

["cust_001", "cust_002"]

Response

Promotional credit granted

statusCode

integer

Example:

201

message

string

Example:

"Promotional credit applied"