Archive a coupon · Ownrecord docs

Archives a coupon: it can't be redeemed any more, directly or through its promotion codes. Discounts already applied with it keep running until they end. Archiving an archived coupon changes nothing. Reactivate it with coupons.update and active: true.

reason is recorded in the audit log.

At a glance

REST: POST /api/v1/coupons/{id}/archive
MCP tool: coupons_archive
Operation ID: coupons.archive
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

Path parameters

Field	Type	Description
`id`	`cpn_…` ID

Body

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

Field	Type	Required	Description
`reason`	string	No

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`cpn_…` ID
`object`	`"coupon"`
`brandId`	`brd_…` ID
`livemode`	boolean
`name`	string
`percentOffPpm`	string or null	Percent off in parts per million (500000 = 50%), or null for an amount-off coupon.
`amountOff`	money or null	Amount off per invoice, or null for a percent-off coupon.
`duration`	one of `once`, `repeating`, `forever`
`durationInPeriods`	integer or null
`appliesTo`	object or null	The products and prices the coupon is limited to, or null for every line.
`maxRedemptions`	integer or null
`redeemBy`	date-time or null
`timesRedeemed`	integer
`valid`	boolean	Whether it can be redeemed now: active, before `redeemBy`, below its limit.
`used`	boolean	A discount references it or a redemption was counted: only name, status and metadata can change.
`active`	boolean
`metadata`	object
`createdAt`	date-time
`updatedAt`	date-time

Examples

End a launch offer

HTTP

POST /api/v1/coupons/cpn_01m4tx5nj8emwbyf7y9vcf47z0/archive
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "reason": "Launch period over"
}

Response (200):

JSON

{
  "id": "cpn_01m4tx5nj8emwbyf7y9vcf47z0",
  "object": "coupon",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "name": "Launch offer",
  "percentOffPpm": "500000",
  "amountOff": null,
  "duration": "repeating",
  "durationInPeriods": 3,
  "appliesTo": {
    "productIds": [],
    "priceIds": ["price_01m4tx5nj8emwbyf7y9vcf47y2"]
  },
  "maxRedemptions": 500,
  "redeemBy": "2027-01-01T00:00:00.000Z",
  "timesRedeemed": 0,
  "valid": false,
  "used": false,
  "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
`resource_not_found`	404	No coupon 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 coupon changed at the same time; 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: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_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#

End a launch offer#

Errors#