Coupons

Discount codes shoppers type at checkout: a percentage or a fixed amount off, with limits on who, when and how often.

Reach them through admin.coupons. Reading needs the marketing:read scope, changing them marketing:write.

List coupons

admin.coupons.list(query?: ListQuery & { code?: string }): Promise<CursorPage<AdminCoupon>>

One page of the shop's coupons, newest first, or oldest change first with updatedSince. Read the next page with meta.nextCursor as cursor. Scope: marketing:read.

Parameters

Query fields

Returns

A CursorPage<AdminCoupon>:

Errors

Example

const { data } = await admin.coupons.list({ code: 'WELCOME10' });
const coupon = data[0];

Iterate over every coupon

admin.coupons.all(query?: ListQuery & { code?: string }): AsyncGenerator<AdminCoupon, void, undefined>

Every coupon matching the query, one at a time, fetching the next page as you read. It takes the same query as list, without cursor. Scope: marketing:read.

Returns

An async generator of AdminCoupon, each:

Example

for await (const coupon of admin.coupons.all({ updatedSince: lastSyncedAt })) {
    await erp.saveCoupon(coupon);
}

Get a coupon

admin.coupons.get(id: number): Promise<AdminCoupon>

One coupon by its id. Scope: marketing:read.

Parameters

Returns

An AdminCoupon:

Errors

Create a coupon

admin.coupons.create(input: AdminCouponInput, options?: RequestOptions): Promise<AdminCoupon>

A new coupon. The code is stored in upper case and must be unique in the shop. Scope: marketing:write.

Parameters

Request fields

Returns

The new AdminCoupon:

Errors

Example

const coupon = await admin.coupons.create({
    code: 'WELCOME10',
    type: 'percentage',
    value: 10,
    firstOrderOnly: true,
    usageLimitPerCustomer: 1,
    endsAt: '2026-12-31T23:59:59Z',
});

Update a coupon

admin.coupons.update(id: number, changes: Partial<AdminCouponInput>, options?: UpdateOptions): Promise<AdminCoupon>

Changes only the fields sent; the coupon must still pass the full rules. Setting status to false switches it off. Scope: marketing:write.

Parameters

Request fields

Returns

The changed AdminCoupon:

Errors

Example

const coupon = await admin.coupons.get(5);
await admin.coupons.update(
    5,
    { value: 15 },
    { unmodifiedSince: coupon.updatedAt ?? undefined },
);

Delete a coupon

admin.coupons.delete(id: number): Promise<void>

Deletes a coupon. Scope: marketing:write.

Parameters

Returns

Nothing.

Errors