v1

latestOpenAPI 3.1.02026-07-222392081.7 MB

Coupons > Promotion codes

Create promotion code

Create a new promotion code.

post/v1/promotion-codes

Request body

codestring required

Promotion code.

coupon_idstring required

Coupon ID.

customer_idstring nullable

If a customer_id is set, this promotion code will only be available to this customer.

plan_idstring nullable

If a plan_id is set, this promotion code will only be available for subscriptions with this plan ID.

product_idstring nullable

If a product_id is set, this promotion code will only be available for subscriptions with this product ID.

expires_atstring date-time nullable

Date and time when the promotion code expires.

max_redemptionsnumber nullable

Maximum number of redemptions for the promotion code. Independent from coupon's max redemptions.

current_redemptionsinteger nullable

Current number of redemptions for the promotion code.

duration_countinteger nullable

Duration count applied to the subscription for the promotion code. 0 or null for once

duration_period'once' | 'days' | 'weeks' | 'months' | 'years' nullable

Duration period applied to the subscription for the promotion code for the promotion code. Valid values are once, days, weeks, months, years

only_for_first_time_orderboolean nullable

Whether the promotion code is only for first time orders. Defaults to false

Example request

{
  "code": "PROMO123",
  "coupon_id": "cou_DKL4Xcb5VSa8CQ",
  "customer_id": "cus_DKL4Xcb5VSa8CQ",
  "plan_id": "plan_DKL4Xcb5VSa8CQ",
  "product_id": "itm_DKL4Xcb5VSa8CQ",
  "expires_at": "2021-01-01T00:00:00.000Z",
  "max_redemptions": 10,
  "duration_count": 1,
  "duration_period": "months"
}

Response

The newly created promotion code

idstring required

Promotion code ID.

codestring required

Promotion code.

coupon_idstring required

Coupon ID.

client_idstring required

Client ID.

customer_idstring nullable required

If a customer_id is set, this promotion code will only be available to this customer.

plan_idstring nullable required

If a plan_id is set, this promotion code will only be available for subscriptions with this plan ID.

product_idstring nullable required

If a product_id is set, this promotion code will only be available for subscriptions with this product ID.

created_atstring date-time required

Promotion code creation date. UTC date time string in the ISO 8601 format.

updated_atstring date-time required

Promotion code last edition date. UTC date time string in the ISO 8601 format.

expires_atstring date-time nullable required

Date and time when the promotion code expires.

max_redemptionsnumber nullable required

Maximum number of redemptions for the promotion code. Independent from coupon's max redemptions.

current_redemptionsnumber nullable required

Current number of redemptions for the promotion code.

duration_countnumber nullable required

Duration count applied to the subscription for the promotion code. 0 or null for once

duration_period'once' | 'days' | 'weeks' | 'months' | 'years' nullable required

Duration period applied to the subscription for the promotion code for the promotion code. Valid values are once, days, weeks, months, years

only_for_first_time_orderboolean nullable required

Whether the promotion code is only for first time orders. Defaults to false

Example response

{
  "id": "promo_DKL4Xcb5VSa8CQ",
  "code": "PROMO123",
  "coupon_id": "cou_DKL4Xcb5VSa8CQ",
  "client_id": "cli_DKL4Xcb5VSa8CQ",
  "customer_id": "cus_DKL4Xcb5VSa8CQ",
  "plan_id": "plan_DKL4Xcb5VSa8CQ",
  "product_id": "itm_DKL4Xcb5VSa8CQ",
  "created_at": "2021-01-01T00:00:00.000Z",
  "updated_at": "2021-01-01T00:00:00.000Z",
  "expires_at": "2021-01-01T00:00:00.000Z",
  "max_redemptions": 10,
  "duration_count": 1,
  "duration_period": "months"
}