Coupons

Create a coupon

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.

post/v1/projects/{project}/coupons

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/projects/{project}/coupons
  • Auth: HTTP bearer

Path parameters

projectstring uuid required

The project, resolved by the route binder.

Headers

Idempotency-Keystring uuid required

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.

Request body

codestring required

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.

namestring required

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

discount_type'percentage' | 'fixed' required
discount_valuenumber required

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

currency_idstring nullable

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.

max_redemptionsinteger nullable

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

max_redemptions_per_userinteger

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

minimum_amountnumber nullable

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

starts_atstring date-time nullable

When redemption opens, ISO 8601. Omit for immediately.

expires_atstring date-time nullable

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

activeboolean

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

plan_idsstring[]

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

Response

The new coupon.

Example response

{
  "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"
    },
    "duration": "once",
    "limits": {
      "max_redemptions": 500,
      "max_redemptions_per_user": 1
    },
    "redemptions": {
      "count": 137,
      "remaining": 363
    },
    "window": {
      "starts_at": "2026-11-27T00:00:00+00:00",
      "expires_at": "2026-12-01T00:00:00+00:00"
    },
    "active": true,
    "redeemable": true,
    "created_at": "2026-11-20T09:14:02+00:00",
    "updated_at": "2026-11-24T16:41:11+00:00"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.