Skip to content
ABUNA
DocsCoupons

API reference

Coupons

Create the discounts customers get with a promotion code, and keep them for one payment, some months, or every payment.

View as Markdown

A coupon is a discount: a percentage off or a fixed amount, for one payment, a number of months, or every payment. Customers use it through a promotion code. You can also apply a coupon yourself when you create a checkout session or a subscription. To run a sale from start to finish, see Run a sale with promotion codes.

The coupon object

Attributes

  • idstring

    Unique identifier for the coupon.
  • app_idstring

    The app the coupon belongs to.
  • namestringnullable

    A name for you, up to 100 characters. Checkout shows it on the discount line when no code brought the coupon.
  • percent_offintegernullable

    The percentage taken off, from 1 to 99. Null when the coupon takes off a fixed amount.
  • amount_offintegernullable

    The fixed amount taken off, in the currency's smallest unit. Null when the coupon takes off a percentage.
  • currencystringnullable

    XAF, XOF or USD. Set with amount_off, and null with percent_off.
  • durationstring

    once: the first charged period. repeating: the periods in duration_in_months. forever: every period. See How long a discount lasts.
  • duration_in_monthsintegernullable

    How many months a repeating coupon lasts, counted from the subscription's start. Null for once and forever.
  • max_redemptionsintegernullable

    The most subscriptions that can use the coupon. Null for no limit.
  • redeem_bytimestampnullable

    The last moment the coupon can be used, in Unix seconds. Null for no end.
  • times_redeemedinteger

    How many subscriptions have used it, through any of its codes or a discount you set.
  • metadataobject

    Your own keys and values. {} when there are none.
  • created_attimestamp

    When the coupon was created, in Unix seconds.
  • applies_toobjectnullable

    The products the coupon is for, as { "products": [...] }. Null when it applies to every product.
  • validboolean

    Whether a new subscription can use the coupon now: it isn't deleted, its redeem_by hasn't passed, and it is under max_redemptions.
The coupon object
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": 1798761600,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": {
    "products": [
      "pR4dWx9K"
    ]
  },
  "valid": true
}

Create a coupon

POST/v1/apps/{appID}/coupons

Accepts an Idempotency-Key header.

Creates a coupon. Send percent_off or amount_off, not both, and a duration.

Parameters

  • namestring

    A name for you, up to 100 characters. Checkout shows it on the discount line when no code brought the coupon.
  • percent_offinteger

    The percentage to take off, from 1 to 99. Rounded down to the currency's smallest unit.
  • amount_offinteger

    The fixed amount to take off, in the currency's smallest unit, like 1000 for FCFA 1,000. Send currency with it.
  • currencystring

    XAF, XOF or USD. Required with amount_off, and not allowed with percent_off.
  • durationstringrequired

    once, repeating or forever.
  • duration_in_monthsinteger

    Required with repeating: how many months the discount lasts, from 1 up. Not allowed with the other durations.
  • max_redemptionsinteger

    The most subscriptions that can use the coupon, at least 1. Omit it for no limit.
  • redeem_bytimestamp

    The last moment the coupon can be used, in Unix seconds. It must be in the future.
  • applies_toobject

    The products the coupon is for. Omit it to cover every product.
    Show child parametersHide child parameters
    • productsarray

      Product IDs, up to 100. An empty list covers every product.
  • metadataobject

    Your own keys and values.

Returns the coupon with status 201. A missing or wrong field returns 422 with code invalid and an errors item for it. A product ID that isn't in the app returns 422 with an errors item for applies_to.products and code not_found.

POST /v1/apps/{appID}/coupons
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "percent_off": 25,
    "duration": "once"
  }'
Response
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "once",
  "duration_in_months": null,
  "max_redemptions": null,
  "redeem_by": null,
  "times_redeemed": 0,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": null,
  "valid": true
}

List coupons

GET/v1/apps/{appID}/coupons

Lists the app's coupons, newest first, one page at a time. Deleted coupons aren't listed.

Query parameters

  • limitinteger

    How many coupons to return, from 1 to 100. Defaults to 50.
  • cursorstring

    The next_cursor from the previous page. Send the same filters with it.

Returns items and next_cursor, as described in Lists and filters. A value that isn't allowed, like a limit above 100, returns 422 with code invalid and the parameter's name in errors.

GET /v1/apps/{appID}/coupons
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "items": [
    {
      "id": "Kf4Wn7Qa",
      "app_id": "8ddhXCDW",
      "name": "Black Friday",
      "percent_off": 25,
      "amount_off": null,
      "currency": null,
      "duration": "repeating",
      "duration_in_months": 3,
      "max_redemptions": 100,
      "redeem_by": 1798761600,
      "times_redeemed": 4,
      "metadata": {},
      "created_at": 1727600000,
      "applies_to": {
        "products": [
          "pR4dWx9K"
        ]
      },
      "valid": true
    }
  ],
  "next_cursor": null
}

Retrieve a coupon

GET/v1/apps/{appID}/coupons/{id}

Returns the coupon. A deleted coupon is not found.

If the app has no coupon with that ID, returns 404 with code not_found.

GET /v1/apps/{appID}/coupons/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": 1798761600,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": {
    "products": [
      "pR4dWx9K"
    ]
  },
  "valid": true
}

Update a coupon

PATCH/v1/apps/{appID}/coupons/{id}

Changes the coupon's name, its metadata, or both. The discount stays as you created it: to change the percentage, the amount, or the duration, create another coupon. Send at least one field.

Parameters

  • namestring

    The new name, up to 100 characters. Send null to remove it.
  • metadataobject

    Your own keys and values. It replaces the metadata you set before.

Returns the coupon. A body with neither field returns 422 with code invalid and an errors item for name. Any other field returns 400 with code invalid_json and an errors item with code unknown_field. If the app has no coupon with that ID, returns 404 with code not_found.

PATCH /v1/apps/{appID}/coupons/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
    "name": "Black Friday sale"
  }'
Response
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday sale",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": 1798761600,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": {
    "products": [
      "pR4dWx9K"
    ]
  },
  "valid": true
}

Delete a coupon

DELETE/v1/apps/{appID}/coupons/{id}

Deletes the coupon. No new subscription can use it or its promotion codes. A subscription that already holds it keeps its discount, and new invoices for that subscription still show it. You can't undo it.

Returns the coupon's ID, deleted: true, and when it was deleted. If the app has no coupon with that ID, or the coupon is already deleted, returns 404 with code not_found.

DELETE /v1/apps/{appID}/coupons/{id}
curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "id": "Kf4Wn7Qa",
  "deleted": true,
  "deleted_at": 1727686400
}

Next steps