Update a promotion code · Ownrecord docs

Archives (active: false) or reactivates (active: true) a promotion code, or replaces its metadata. The code and its restrictions never change: archive the code and create a new one instead. A reactivated code still needs a redeemable coupon to be used.

At a glance

REST: PATCH /api/v1/promotion_codes/{id}
MCP tool: promotion_codes_update
Operation ID: promotion_codes.update
Scope: Brand
Permission: catalog:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the catalog:write scope
Since: M5

Request

Path parameters

Field	Type	Description
`id`	`promo_…` ID

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`active`	boolean	No	false archives the code, true reactivates it.
`metadata`	object	No	Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.

Response

200 OK 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

Pause a code

HTTP

PATCH /api/v1/promotion_codes/promo_01m4tx5nj8emwbyf7y9vcf47z2
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "active": false
}

Response (200):

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": false,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	Neither `active` nor `metadata` was sent.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	No promotion code with this ID is visible to the request.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The code changed at the same time (for example a redemption); retry.	Fetch the object again and retry the change.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Pause a code#

Errors#