# Create a promotion code > The promotion_codes.create operation: POST /api/v1/promotion_codes in the REST API and the promotion_codes_create tool in the MCP server. Creates a customer-facing code for a coupon, such as `LAUNCH50`. Customers enter it at checkout (any case); codes are unique in the brand and mode and are never reused, archived ones included. `restrictions` limit who can use it and when: `firstTimeOnly` (no earlier successful payment or paid invoice), `minimumAmount` (the purchase before discounts, same currency), `customerId`, `expiresAt` and `maxRedemptions`. They are checked when the code is applied; redemptions are counted on successful payment. The code and its restrictions can't change later: archive it and create another. ## At a glance - **REST:** `POST /api/v1/promotion_codes` - **MCP tool:** `promotion_codes_create` - **Operation ID:** `promotion_codes.create` - **Scope:** Brand - **Permission:** `catalog:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `catalog:write` scope - **Since:** M5 ## Request ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------------------------------- | ---------- | -------- | -------------------------------------------------------------------------------------- | | `couponId` | `cpn_…` ID | Yes | The coupon customers get with the code. | | `code` | string | Yes | What customers type, e.g. LAUNCH50. Case doesn't matter; unique in the brand and mode. | | `restrictions` | object | No | Who can use the code and when. They can't change later: create a new code instead. | | `restrictions.firstTimeOnly` | boolean | No | Only customers without an earlier successful payment or paid invoice. | | `restrictions.minimumAmount` | object | No | The purchase before discounts must reach this amount, in the same currency. | | `restrictions.minimumAmount.amount` | string | Yes | Integer micros as a string (12500000 = 12.50). | | `restrictions.minimumAmount.currency` | string | Yes | ISO 4217 currency code: the price's currency. | | `restrictions.customerId` | `cus_…` ID | No | Only this customer can use the code. | | `restrictions.expiresAt` | date-time | No | The code can't be used from this instant on. | | `restrictions.maxRedemptions` | integer | No | How many times it can be redeemed in total (counted on successful payment). | | `active` | boolean | No | Default true; false creates it archived. | | `metadata` | object | No | Your own key-value pairs (at most 50 keys). On updates the whole set is replaced. | ## Response `201 Created` with a JSON object: | Field | Type | Description | | ----------------------------- | ------------------ | ---------------------------------------------- | | `id` | `promo_…` ID | | | `object` | `"promotion_code"` | | | `brandId` | `brd_…` ID | | | `livemode` | boolean | | | `couponId` | `cpn_…` ID | | | `code` | string | As entered; customers may type it in any case. | | `restrictions` | object | | | `restrictions.firstTimeOnly` | boolean | | | `restrictions.minimumAmount` | money or null | | | `restrictions.customerId` | string or null | | | `restrictions.expiresAt` | date-time or null | | | `restrictions.maxRedemptions` | integer or null | | | `timesRedeemed` | integer | | | `active` | boolean | | | `metadata` | object | | | `createdAt` | date-time | | | `updatedAt` | date-time | | ## Examples ### A launch code for first-time customers ```http POST /api/v1/promotion_codes Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "couponId": "cpn_01m4tx5nj8emwbyf7y9vcf47z0", "code": "LAUNCH50", "restrictions": { "firstTimeOnly": true, "maxRedemptions": 200 } } ``` Response (`201`): ```json { "id": "promo_01m4tx5nj8emwbyf7y9vcf47z2", "object": "promotion_code", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "couponId": "cpn_01m4tx5nj8emwbyf7y9vcf47z0", "code": "LAUNCH50", "restrictions": { "firstTimeOnly": true, "minimumAmount": null, "customerId": null, "expiresAt": null, "maxRedemptions": 200 }, "timesRedeemed": 0, "active": true, "metadata": {}, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | The code or a restriction is malformed, or `expiresAt` is in the past. | Fix the fields listed in `details.issues` and send the request again. | | [`promotion_code_taken`](https://ownrecord.io/docs/reference/errors.md#promotion_code_taken) | 409 | The brand already has this code in this mode (in any case). | Choose another code. Codes are compared without regard to case and are never reused. | | [`coupon_not_redeemable`](https://ownrecord.io/docs/reference/errors.md#coupon_not_redeemable) | 409 | The coupon is archived, expired or used up. | Check `details.reason`: reactivate an archived coupon, or create a new coupon when it expired or reached its redemption limit. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | The coupon or the restricted customer isn't in this brand and mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`customer_deleted`](https://ownrecord.io/docs/reference/errors.md#customer_deleted) | 400 | The restricted customer was deleted. | Create a new customer for this buyer. Deleted customers stay readable for the records they belong to, but can't be changed. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't change this brand's catalog. | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).