Skip to main content
POST
/
coupons
Create coupon
curl --request POST \
  --url https://api.withorb.com/v1/coupons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "redemption_code": "<string>",
  "discount": {
    "discount_type": "percentage",
    "percentage_discount": 123
  },
  "duration_in_months": 12,
  "max_redemptions": 500000000
}
'
{
  "id": "<string>",
  "redemption_code": "<string>",
  "discount": {
    "discount_type": "percentage",
    "percentage_discount": 0.5,
    "applies_to_price_ids": [
      "h74gfhdjvn7ujokd",
      "7hfgtgjnbvc3ujkl"
    ],
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ],
    "reason": "<string>"
  },
  "times_redeemed": 123,
  "duration_in_months": 12,
  "max_redemptions": 123,
  "archived_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Body

application/json
​
redemption_code
string
required

This string can be used to redeem this coupon for a given subscription.

Example:

"HALFOFF"

​
discount
NewCouponPercentageDiscount · object
required
​
duration_in_months
integer | null

This allows for a coupon's discount to apply for a limited time (determined in months); a null value here means "unlimited time".

Required range: 1 <= x <= 120
Example:

12

​
max_redemptions
integer | null

The maximum number of redemptions allowed for this coupon before it is exhausted;null here means "unlimited".

Required range: 1 <= x <= 1000000000

Response

Created

A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users.

​
id
string
required

Also referred to as coupon_id in this documentation.

Example:

"7iz2yanVjQoBZhyH"

​
redemption_code
string
required

This string can be used to redeem this coupon for a given subscription.

Example:

"HALFOFF"

​
discount
PercentageDiscount · object
required
​
times_redeemed
integer
required

The number of times this coupon has been redeemed.

​
duration_in_months
integer | null
required

This allows for a coupon's discount to apply for a limited time (determined in months); a null value here means "unlimited time".

Example:

12

​
max_redemptions
integer | null
required

The maximum number of redemptions allowed for this coupon before it is exhausted; null here means "unlimited".

​
archived_at
string<date-time> | null
required

An archived coupon can no longer be redeemed. Active coupons will have a value of null for archived_at; this field will be non-null for archived coupons.