List coupons
The coupons.list operation: GET /api/v1/coupons in the REST API and the coupons_list tool in the MCP server.
GET
/api/v1/couponsLists the brand's coupons in the request's mode, newest first, with their name, discount and duration: look
one up by its name here. Filter with active=true (or false for archived ones).
Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).
At a glance
- REST:
GET /api/v1/coupons - MCP tool:
coupons_list - Operation ID:
coupons.list - Scope: Brand
- Permission:
catalog:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Pagination:
limit(at most 100) andstarting_after - Authentication: API key with the
catalog:readscope - Since: M5
Request
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
active | string | No | Only active (true) or archived (false) coupons. |
limit | integer (1 to 100) | No | |
starting_after | cpn_… ID | No |
Response
200 OK with a JSON object, a page of the list (newest first):
| Field | Type | Description |
|---|---|---|
object | "list" | |
data | array of object | |
data[].id | cpn_… ID | |
data[].object | "coupon" | |
data[].brandId | brd_… ID | |
data[].livemode | boolean | |
data[].name | string | |
data[].percentOffPpm | string or null | Percent off in parts per million (500000 = 50%), or null for an amount-off coupon. |
data[].amountOff | money or null | Amount off per invoice, or null for a percent-off coupon. |
data[].duration | one of once, repeating, forever | |
data[].durationInPeriods | integer or null | |
data[].appliesTo | object or null | The products and prices the coupon is limited to, or null for every line. |
data[].maxRedemptions | integer or null | |
data[].redeemBy | date-time or null | |
data[].timesRedeemed | integer | |
data[].valid | boolean | Whether it can be redeemed now: active, before redeemBy, below its limit. |
data[].used | boolean | A discount references it or a redemption was counted: only name, status and metadata can change. |
data[].active | boolean | |
data[].metadata | object | |
data[].createdAt | date-time | |
data[].updatedAt | date-time | |
has_more | boolean | |
next_cursor | cpn_… ID or null |
Examples
Active coupons
HTTP
GET /api/v1/coupons?active=true
Authorization: Bearer or_test_…
Response (200):
JSON
{
"object": "list",
"data": [
{
"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": true,
"used": false,
"active": true,
"metadata": {},
"createdAt": "2026-10-13T12:00:00.000Z",
"updatedAt": "2026-10-13T12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | A filter or pagination value is malformed. | Fix the fields listed in details.issues and send the request again. |
permission_denied | 403 | You can't see 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, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.