Realize promo code on platform

Marks code sold to customer: available → realized.

Why this method exists

Marks code sold to customer: available → realized.

When to use

On successful checkout; Idempotency-Key per order.

Endpoint

POST /v1/platform/promo-codes/realize

Authentication: X-Api-Key header (prefix bk_plt_). Do not send projectId or actor id in body — they come from the key.

Scope: platform:codes:realize

Request example

{
  "meta": { "requestId": "optional-uuid" },
  "data": { "codeId": "code-uuid", "externalRef": "order-554433", "realizedRef": "checkout-xyz" }
}

Response example

{
  "success": true,
  "data": {
    "codeId": "code-uuid",
    "codeDisplay": "QUEEN14-48AMU",
    "status": "realized",
    "platformId": "platform-uuid",
    "realizedAt": "2026-07-13T11:00:00Z",
    "realizedChannel": "Ригла"
  }
}

Errors

UNAUTHORIZED / ACCESS_DENIED — access denied
VALIDATION_ERROR — invalid body
NOT_FOUND — resource not found
RATE_LIMIT_EXCEEDED (429) — rate limit

cURL

curl -X POST "https://api-external.promanta.ru/v1/platform/promo-codes/realize" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"data": { "codeId": "code-uuid", "externalRef": "order-554433", "realizedRef": "checkout-xyz" }}'