Skip to content
ABUNA
DocsPromotion codes

API reference

Promotion codes

Give a coupon codes customers type at checkout, each with its own end date, limit and first-time rule.

View as Markdown

A promotion code is the word a customer types to get a coupon, like BLACKFRIDAY. One coupon can have many codes, each active or not, with its own end date and limit. Codes ignore case, so blackfriday works too.

The promotion code object

Attributes

  • idstring

    Unique identifier for the code. Customers type the code, not this ID.
  • app_idstring

    The app the code belongs to.
  • codestring

    The text customers type at checkout, like BLACKFRIDAY.
  • activeboolean

    Whether customers can use the code. A code you turn off keeps its uses and its coupon.
  • expires_attimestampnullable

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

    The most subscriptions that can use the code. Null for no limit.
  • times_redeemedinteger

    How many subscriptions have used the code. It can pass max_redemptions; see List promotion codes.
  • metadataobject

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

    When the code was created, in Unix seconds.
  • couponobject

    The coupon the code gives.
  • restrictionsobject

    Who can use the code.
    Show child attributesHide child attributes
    • first_time_transactionboolean

      When true, only a customer of this app who has never paid an invoice can use it. The check uses the customer's email address.
The promotion code object
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": true,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "coupon": {
    "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Create a promotion code

POST/v1/apps/{appID}/promotion-codes

Accepts an Idempotency-Key header.

Creates a code for one of the app's coupons.

Parameters

  • couponstringrequired

    The ID of the coupon the code gives. The coupon must not be deleted, past its redeem_by, or out of uses.
  • codestring

    The text customers type. Use 1 to 50 letters, digits, hyphens, or underscores. Codes ignore case and must be unique in the app. Omit it and Abuna makes a code of 8 characters you can read out.
  • activeboolean

    Whether customers can use it right away. Defaults to true.
  • expires_attimestamp

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

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

    Who can use the code. Omit it for everyone.
    Show child parametersHide child parameters
    • first_time_transactionboolean

      Set it to true so only a customer who never paid this app can use the code.
  • metadataobject

    Your own keys and values.

Returns the code with its coupon and status 201. A missing or wrong field returns 422 with code invalid and an errors item for it. A coupon ID that isn't in the app returns 422 with code not_found for coupon. A coupon that can't be used returns 422 with code invalid for coupon. A code another promotion code in the app already has returns 409 with code code_taken for code.

POST /v1/apps/{appID}/promotion-codes
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "coupon": "Kf4Wn7Qa",
    "code": "BLACKFRIDAY",
    "max_redemptions": 100
  }'
Response
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": true,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 0,
  "metadata": {},
  "created_at": 1727600000,
  "coupon": {
    "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

List promotion codes

GET/v1/apps/{appID}/promotion-codes

Lists the app's promotion codes, newest first, one page at a time. Each item carries its coupon.

Query parameters

  • codestring

    Only the code with this text. Case doesn't matter.
  • couponstring

    Only this coupon's codes.
  • limitinteger

    How many promotion codes 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.

A code can be used by more subscriptions than its max_redemptions if customers were already paying when the last place filled. times_redeemed shows the real count.

GET /v1/apps/{appID}/promotion-codes
curl "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY" \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "items": [
    {
      "id": "Wm9Tb2Xs",
      "app_id": "8ddhXCDW",
      "code": "BLACKFRIDAY",
      "active": true,
      "expires_at": 1798761600,
      "max_redemptions": 100,
      "times_redeemed": 4,
      "metadata": {},
      "created_at": 1727600000,
      "coupon": {
        "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
      },
      "restrictions": {
        "first_time_transaction": false
      }
    }
  ],
  "next_cursor": null
}

Retrieve a promotion code

GET/v1/apps/{appID}/promotion-codes/{id}

Returns the code and its coupon.

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

GET /v1/apps/{appID}/promotion-codes/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": true,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "coupon": {
    "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Update a promotion code

PATCH/v1/apps/{appID}/promotion-codes/{id}

Turns the code on or off, changes its metadata, or both. The code, its coupon, its end date and its limits stay as you created them. Send at least one field.

Parameters

  • activeboolean

    Whether customers can use the code. Send false to stop new uses. Subscriptions that already used it keep their discount.
  • metadataobject

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

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

PATCH /v1/apps/{appID}/promotion-codes/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
    "active": false
  }'
Response
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": false,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 7,
  "metadata": {},
  "created_at": 1727600000,
  "coupon": {
    "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Next steps