Coupons API

A coupon is one code many subscribers can redeem for money off at checkout: the multi-redemption counterpart to an access code, which is one code for one person and grants access outright without a payment.

Coupons require the Coupons Addon, or a Growth plan. Every write is refused with 403 TEAM_TIER_REQUIRED if the creator is not entitled, and entitlement is re-checked again when a subscriber actually redeems.

Endpoints

GET/v1/projects/{project}/couponsList a project's coupons POST/v1/projects/{project}/couponsCreate a coupon GET/v1/projects/{project}/coupons/{coupon}Get a coupon PATCH/v1/projects/{project}/coupons/{coupon}Update a coupon DELETE/v1/projects/{project}/coupons/{coupon}Delete a coupon POST/v1/projects/{project}/coupons/{coupon}/activateActivate a coupon POST/v1/projects/{project}/coupons/{coupon}/deactivateDeactivate a coupon

List a project's coupons

GET

curl "https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/coupons?active=true&per_page=25&page=1" \  -H "Authorization: Bearer sbt_..."

Pages the project's coupons, newest first. active filters on the creator's on/off switch only; code finds one exact code.

active=true is not the same as redeemable. A coupon can be switched on and still not apply: outside its window, fully claimed, or capped for that subscriber. Read redeemable on each row for the combined answer.

Requires ability

project-coupon:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_coupons

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Query Parameters

active?boolean

Keep only coupons whose on/off switch is in this position. Not the same as redeemable: read redeemable on each row for the combined answer.

code?string

Find one coupon by its exact code, compared in upper case.

page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value

Default1

per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 25.

Range1 <= value <= 100

Default25

sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"

sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

"asc"
"desc"

Responses

200OKapplication/json

The page.

data*array<>

The items on this page.

links*

Links to the first, last, previous and next pages.

meta*

The paging counters for this page.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons?code=BLACKFRIDAY"

{  "data": [    {      "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "code": "BLACKFRIDAY",      "name": "Black Friday 2026",      "discount": {        "type": "percentage",        "value": "25.0000",        "currency_id": null,        "currency": null      },      "duration": "once",      "limits": {        "max_redemptions": 500,        "max_redemptions_per_user": 1,        "minimum_amount": null      },      "redemptions": {        "count": 137,        "remaining": 363,        "exhausted": false      },      "window": {        "starts_at": "2026-11-27T00:00:00+00:00",        "expires_at": "2026-12-01T00:00:00+00:00"      },      "plan_ids": {        "property1": null,        "property2": null      },      "active": true,      "redeemable": true,      "created_at": "2026-11-20T09:14:02+00:00",      "updated_at": "2026-11-24T16:41:11+00:00"    }  ],  "links": {    "first": "string",    "last": "string",    "prev": "string",    "next": "string"  },  "meta": {    "current_page": 1,    "from": 1,    "last_page": 1,    "links": [      {        "url": "string",        "label": "string",        "active": true      }    ],    "path": "string",    "per_page": 0,    "to": 1,    "total": 0  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: CouponResource[];  links: Links;  meta: Meta;}export interface CouponResource {  id: string;  project_id: string;  code: string;  name: string;  discount: Discount;  duration: string;  limits: Limits;  redemptions: Redemptions;  window: Window;  plan_ids: Record<string, unknown>;  active: boolean;  redeemable: boolean;  created_at: string | null;  updated_at: string | null;}export interface Discount {  type: string;  value: string;  currency_id: string | null;  currency?: string | null;}export interface Limits {  max_redemptions: number | null;  max_redemptions_per_user: number;  minimum_amount: string | null;}export interface Redemptions {  count: number;  remaining: number | null;  exhausted: boolean;}export interface Window {  starts_at: string | null;  expires_at: string | null;}export interface Links {  first: string | null;  last: string | null;  prev: string | null;  next: string | null;}export interface Meta {  current_page: number;  from: number | null;  last_page: number;  links: Link[];  path: string | null;  per_page: number;  to: number | null;  total: number;}export interface Link {  url: string | null;  label: string;  active: boolean;}

Create a coupon

POST

curl -X POST https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/coupons \  -H "Authorization: Bearer sbt_..." \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{    "code": "BLACKFRIDAY",    "name": "Black Friday 2026",    "discount_type": "percentage",    "discount_value": 25,    "max_redemptions": 500,    "max_redemptions_per_user": 1,    "starts_at": "2026-11-27T00:00:00Z",    "expires_at": "2026-12-01T00:00:00Z",    "active": true  }'

Answers 201 with the coupon. duration is not yours to set: only first-payment discounts exist today, so it is always once on the way out.

code is uppercased before the uniqueness check. Sending blackfriday when BLACKFRIDAY exists in the project is a 422, not a second coupon. Uniqueness is per project, so two different projects may both have BLACKFRIDAY.

Requires ability

project-coupon:create

The token must hold this ability, or the call is refused with 403.

Fires one event

coupon.created

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

create_coupon

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

A coupon to create: the code, what comes off, how often it may be used and when.

code*string

The code subscribers type, 3 to 64 letters, numbers and dashes. Stored and matched in upper case, and uppercased before the uniqueness check: blackfriday when BLACKFRIDAY exists in the project is refused, not a second coupon. Two projects may both hold the same code.

Match^[A-Za-z0-9-]+$

Length3 <= length <= 64

name*string

A creator-facing label, 3 to 255 characters, never shown to subscribers.

Length3 <= length <= 255

discount_type*CouponDiscountType

percentage or fixed.

Value in

"percentage"
"fixed"

discount_value*number

Greater than 0; at most 100 when discount_type is percentage.

currency_id?|

Required when discount_type is fixed, and it must match the currency of the plans the coupon applies to. Refused as meaningless on a percentage coupon.

duration?"once"

Accepted for forward compatibility but only once is honoured: first-payment discounts are the only kind that exist today.

Value in

"once"

max_redemptions?|

The total cap across everyone, 1 to 1,000,000. Omit or send null for unlimited.

Range1 <= value <= 1000000

max_redemptions_per_user?integer

How many times one member may redeem the code, 1 to 1,000. Defaults to 1.

Range1 <= value <= 1000

minimum_amount?|

The order floor, in the plan's own currency; greater than 0.

starts_at?|

When redemption opens, ISO 8601. Omit for immediately.

Formatdate-time

expires_at?|

When redemption closes, ISO 8601; must be after starts_at. Omit for never.

Formatdate-time

active?boolean

Whether the code can be redeemed from the start. Defaults to true.

plan_ids?array<>

Restrict the code to these plans of the project, at most 200. Omit or send [] for every plan, including plans added later.

Itemsitems <= 200

Responses

201Createdapplication/json

The new coupon.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when a field is invalid, the code is taken in the project, a fixed discount has no currency, or a percentage is above 100; error.fields names the key.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "code": "string",    "name": "string",    "discount_type": "percentage",    "discount_value": 0  }'

{  "data": {    "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "code": "BLACKFRIDAY",    "name": "Black Friday 2026",    "discount": {      "type": "percentage",      "value": "25.0000",      "currency_id": null,      "currency": null    },    "duration": "once",    "limits": {      "max_redemptions": 500,      "max_redemptions_per_user": 1,      "minimum_amount": null    },    "redemptions": {      "count": 137,      "remaining": 363,      "exhausted": false    },    "window": {      "starts_at": "2026-11-27T00:00:00+00:00",      "expires_at": "2026-12-01T00:00:00+00:00"    },    "plan_ids": {      "property1": null,      "property2": null    },    "active": true,    "redeemable": true,    "created_at": "2026-11-20T09:14:02+00:00",    "updated_at": "2026-11-24T16:41:11+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface StoreCouponRequest {  code: string;  name: string;  discount_type: "percentage" | "fixed";  discount_value: number;  currency_id?: string | null;  duration?: "once";  max_redemptions?: number | null;  max_redemptions_per_user?: number;  minimum_amount?: number | null;  starts_at?: string | null;  expires_at?: string | null;  active?: boolean;  plan_ids?: string[];}

Response

export interface Response {  data: CouponResource;}export interface CouponResource {  id: string;  project_id: string;  code: string;  name: string;  discount: Discount;  duration: string;  limits: Limits;  redemptions: Redemptions;  window: Window;  plan_ids: Record<string, unknown>;  active: boolean;  redeemable: boolean;  created_at: string | null;  updated_at: string | null;}export interface Discount {  type: string;  value: string;  currency_id: string | null;  currency?: string | null;}export interface Limits {  max_redemptions: number | null;  max_redemptions_per_user: number;  minimum_amount: string | null;}export interface Redemptions {  count: number;  remaining: number | null;  exhausted: boolean;}export interface Window {  starts_at: string | null;  expires_at: string | null;}

Get a coupon

GET

One coupon with its currency ISO code loaded. A coupon of another project, or a deleted one, is 404 RESOURCE_NOT_FOUND.

Three fields that are easy to misread

plan_ids: [] means every plan, not no plans. An empty array is how the coupon itself reads an empty plan relation: the code applies to every plan in the project, including plans added later. Treating it as "restricted to nothing" inverts the meaning.

redemptions.remaining is derived, not stored. Prefer it over computing max_redemptions - count yourself. The quota counts settled redemptions plus reservations whose hold has not expired, so an in-flight checkout is already accounted for, and an abandoned one returns its slot without any sweeper job. Your own subtraction will disagree.

discount.value is a decimal string with four places: "25.0000" for 25% off, "10.0000" for ten of the coupon's currency. Parse it as a decimal, never a float. currency_id is null on a percentage coupon and set on a fixed-amount one, because a percentage applies to a plan in any currency and a fixed amount only to plans priced in its own.

currency (the ISO code) is present only when the relation is loaded: on a single read, a create and an update, not on every list row.

Requires ability

project-coupon:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_coupon

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

coupon*string

The coupon, resolved within the project by the route binder.

Formatuuid

Responses

200OKapplication/json

The coupon.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "code": "BLACKFRIDAY",    "name": "Black Friday 2026",    "discount": {      "type": "percentage",      "value": "25.0000",      "currency_id": null,      "currency": null    },    "duration": "once",    "limits": {      "max_redemptions": 500,      "max_redemptions_per_user": 1,      "minimum_amount": null    },    "redemptions": {      "count": 137,      "remaining": 363,      "exhausted": false    },    "window": {      "starts_at": "2026-11-27T00:00:00+00:00",      "expires_at": "2026-12-01T00:00:00+00:00"    },    "plan_ids": [],    "active": true,    "redeemable": true,    "created_at": "2026-11-20T09:14:02+00:00",    "updated_at": "2026-11-24T16:41:11+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: CouponResource;}export interface CouponResource {  id: string;  project_id: string;  code: string;  name: string;  discount: Discount;  duration: string;  limits: Limits;  redemptions: Redemptions;  window: Window;  plan_ids: Record<string, unknown>;  active: boolean;  redeemable: boolean;  created_at: string | null;  updated_at: string | null;}export interface Discount {  type: string;  value: string;  currency_id: string | null;  currency?: string | null;}export interface Limits {  max_redemptions: number | null;  max_redemptions_per_user: number;  minimum_amount: string | null;}export interface Redemptions {  count: number;  remaining: number | null;  exhausted: boolean;}export interface Window {  starts_at: string | null;  expires_at: string | null;}

Update a coupon

PATCH

Accepts the same fields as create, all optional. Changing terms is not retroactive: subscribers who already redeemed keep exactly what they paid, and the change applies to redemptions from that point on.

Raising max_redemptions on an exhausted coupon makes it redeemable again. Lowering it below the current count does not claw anything back; the coupon simply reports remaining: 0. Answers 200 with the coupon.

Requires ability

project-coupon:update

The token must hold this ability, or the call is refused with 403.

Fires one event

coupon.updated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

update_coupon

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

coupon*string

The coupon, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Request body

JSONWhat the request carriesOptionalapplication/json

The changes to a coupon: any subset of the create shape. A change is never retroactive; subscribers who already redeemed keep exactly what they paid.

code?string

A new code, 3 to 64 letters, numbers and dashes, uppercased before the uniqueness check against the project's other live coupons.

Match^[A-Za-z0-9-]+$

Length3 <= length <= 64

name?string

A new creator-facing label, 3 to 255 characters.

Length3 <= length <= 255

discount_type?CouponDiscountType

percentage or fixed.

Value in

"percentage"
"fixed"

discount_value?number

Greater than 0; at most 100 when the coupon is, or becomes, a percentage.

currency_id?|

Required when the coupon is, or becomes, fixed and it has no currency yet; refused as meaningless on a percentage coupon.

duration?"once"

Accepted for forward compatibility but only once is honoured.

Value in

"once"

max_redemptions?|

The new total cap, 1 to 1,000,000, or null for unlimited. Raising it on an exhausted coupon makes it redeemable again; lowering it below the current count claws nothing back, the coupon simply reports remaining: 0.

Range1 <= value <= 1000000

max_redemptions_per_user?integer

How many times one member may redeem the code, 1 to 1,000.

Range1 <= value <= 1000

minimum_amount?|

The order floor, in the plan's own currency; greater than 0, or null for none.

starts_at?|

When redemption opens, ISO 8601, or null for immediately.

Formatdate-time

expires_at?|

When redemption closes, ISO 8601, or null for never.

Formatdate-time

active?boolean

The on/off switch; prefer the activate and deactivate endpoints, which fire their own events.

plan_ids?array<>

The plans to restrict the code to, at most 200; [] opens it to every plan.

Itemsitems <= 200

Responses

200OKapplication/json

The coupon after the change.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when a field is invalid or the new code is taken by another live coupon of the project.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "code": "BLACKFRIDAY",    "name": "Black Friday 2026",    "discount": {      "type": "percentage",      "value": "25.0000",      "currency_id": null,      "currency": null    },    "duration": "once",    "limits": {      "max_redemptions": 500,      "max_redemptions_per_user": 1,      "minimum_amount": null    },    "redemptions": {      "count": 137,      "remaining": 363,      "exhausted": false    },    "window": {      "starts_at": "2026-11-27T00:00:00+00:00",      "expires_at": "2026-12-01T00:00:00+00:00"    },    "plan_ids": {      "property1": null,      "property2": null    },    "active": true,    "redeemable": true,    "created_at": "2026-11-20T09:14:02+00:00",    "updated_at": "2026-11-24T16:41:11+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface UpdateCouponRequest {  code?: string;  name?: string;  discount_type?: "percentage" | "fixed";  discount_value?: number;  currency_id?: string | null;  duration?: "once";  max_redemptions?: number | null;  max_redemptions_per_user?: number;  minimum_amount?: number | null;  starts_at?: string | null;  expires_at?: string | null;  active?: boolean;  plan_ids?: string[];}

Response

export interface Response {  data: CouponResource;}export interface CouponResource {  id: string;  project_id: string;  code: string;  name: string;  discount: Discount;  duration: string;  limits: Limits;  redemptions: Redemptions;  window: Window;  plan_ids: Record<string, unknown>;  active: boolean;  redeemable: boolean;  created_at: string | null;  updated_at: string | null;}export interface Discount {  type: string;  value: string;  currency_id: string | null;  currency?: string | null;}export interface Limits {  max_redemptions: number | null;  max_redemptions_per_user: number;  minimum_amount: string | null;}export interface Redemptions {  count: number;  remaining: number | null;  exhausted: boolean;}export interface Window {  starts_at: string | null;  expires_at: string | null;}

Delete a coupon

DELETE

curl -X DELETE https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/coupons/4b9d3e08-a1f6-4275-9c83-7e01d6a2f594 \  -H "Authorization: Bearer sbt_..." \  -H "Idempotency-Key: $(uuidgen)"

Removes the code and its redemption history; deactivating keeps both. Answers 204 with no body.

A delete can be refused. If any subscriber holds a live reservation, a checkout in flight with this discount already quoted to a payment provider, the delete answers 422 and asks you to deactivate instead.

Requires ability

project-coupon:delete

The token must hold this ability, or the call is refused with 403.

Fires one event

coupon.deleted

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

delete_coupon

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

coupon*string

The coupon, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

204No content

No content

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

When a checkout with the code is still in flight; error.context.coupon carries the reason.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

No body on this response.

Activate a coupon

POST

Switches the code on so new redemptions are accepted again, within its window and cap. Emits coupon.activated rather than coupon.updated, so an automation watching availability has one event to subscribe to. Answers 200 with the coupon.

Requires ability

project-coupon:update

The token must hold this ability, or the call is refused with 403.

Fires one event

coupon.activated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

activate_coupon

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

coupon*string

The coupon, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

200OKapplication/json

The coupon after the change.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons/497f6eca-6276-4993-bfeb-53cbbbba6f08/activate" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "code": "BLACKFRIDAY",    "name": "Black Friday 2026",    "discount": {      "type": "percentage",      "value": "25.0000",      "currency_id": null,      "currency": null    },    "duration": "once",    "limits": {      "max_redemptions": 500,      "max_redemptions_per_user": 1,      "minimum_amount": null    },    "redemptions": {      "count": 137,      "remaining": 363,      "exhausted": false    },    "window": {      "starts_at": "2026-11-27T00:00:00+00:00",      "expires_at": "2026-12-01T00:00:00+00:00"    },    "plan_ids": {      "property1": null,      "property2": null    },    "active": true,    "redeemable": true,    "created_at": "2026-11-20T09:14:02+00:00",    "updated_at": "2026-11-24T16:41:11+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: CouponResource;}export interface CouponResource {  id: string;  project_id: string;  code: string;  name: string;  discount: Discount;  duration: string;  limits: Limits;  redemptions: Redemptions;  window: Window;  plan_ids: Record<string, unknown>;  active: boolean;  redeemable: boolean;  created_at: string | null;  updated_at: string | null;}export interface Discount {  type: string;  value: string;  currency_id: string | null;  currency?: string | null;}export interface Limits {  max_redemptions: number | null;  max_redemptions_per_user: number;  minimum_amount: string | null;}export interface Redemptions {  count: number;  remaining: number | null;  exhausted: boolean;}export interface Window {  starts_at: string | null;  expires_at: string | null;}

Deactivate a coupon

POST

curl -X POST https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/coupons/4b9d3e08-a1f6-4275-9c83-7e01d6a2f594/deactivate \  -H "Authorization: Bearer sbt_..." \  -H "Idempotency-Key: $(uuidgen)"

The safe way to retire a code: new redemptions stop immediately and every redemption already recorded is kept. A checkout already in flight with the code still completes, so expect a late coupon.redeemed shortly after. Emits coupon.deactivated. Answers 200 with the coupon.

Requires ability

project-coupon:update

The token must hold this ability, or the call is refused with 403.

Fires one event

coupon.deactivated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

deactivate_coupon

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

coupon*string

The coupon, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

200OKapplication/json

The coupon after the change.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/coupons/497f6eca-6276-4993-bfeb-53cbbbba6f08/deactivate" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "code": "BLACKFRIDAY",    "name": "Black Friday 2026",    "discount": {      "type": "percentage",      "value": "25.0000",      "currency_id": null,      "currency": null    },    "duration": "once",    "limits": {      "max_redemptions": 500,      "max_redemptions_per_user": 1,      "minimum_amount": null    },    "redemptions": {      "count": 137,      "remaining": 363,      "exhausted": false    },    "window": {      "starts_at": "2026-11-27T00:00:00+00:00",      "expires_at": "2026-12-01T00:00:00+00:00"    },    "plan_ids": {      "property1": null,      "property2": null    },    "active": true,    "redeemable": true,    "created_at": "2026-11-20T09:14:02+00:00",    "updated_at": "2026-11-24T16:41:11+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: CouponResource;}export interface CouponResource {  id: string;  project_id: string;  code: string;  name: string;  discount: Discount;  duration: string;  limits: Limits;  redemptions: Redemptions;  window: Window;  plan_ids: Record<string, unknown>;  active: boolean;  redeemable: boolean;  created_at: string | null;  updated_at: string | null;}export interface Discount {  type: string;  value: string;  currency_id: string | null;  currency?: string | null;}export interface Limits {  max_redemptions: number | null;  max_redemptions_per_user: number;  minimum_amount: string | null;}export interface Redemptions {  count: number;  remaining: number | null;  exhausted: boolean;}export interface Window {  starts_at: string | null;  expires_at: string | null;}

Coupon CodesThe feature walkthrough.Coupons AddonPricing, and which payment methods can discount.coupon.* eventsThe seven events; coupon.redeemed fires per checkout that settles with the code and coupon.exhausted when the last slot under the cap is taken, neither from a call here.Access Codes APIOne code, one person, grants access.Ability ReferenceHow project-coupon:* maps onto team roles.

Coupons API

EndpointsCopy Anchor Link

List a project's couponsCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Create a couponCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Get a couponCopy Anchor Link

Three fields that are easy to misread

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Update a couponCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Delete a couponCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Activate a couponCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Deactivate a couponCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

Endpoints

List a project's coupons

Authorization

Path Parameters

Query Parameters

Responses

Create a coupon

Authorization

Path Parameters

Header Parameters

Request body

Responses

Get a coupon

Authorization

Path Parameters

Responses

Update a coupon

Authorization

Path Parameters

Header Parameters

Request body

Responses

Delete a coupon

Authorization

Path Parameters

Header Parameters

Responses

Activate a coupon

Authorization

Path Parameters

Header Parameters

Responses

Deactivate a coupon

Authorization

Path Parameters

Header Parameters

Responses