Create Coupon

POST

/api/:account_id/coupons/

POST

/api/:account_id/coupons/

$ curl -X POST https://app.paymentkit.com/api/account_id/coupons/ \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "discount_type": "amount_off"
> }'

1 {
2   "id": "c9f1a7d2-4b3e-4f8a-9d2e-1a2b3c4d5e6f",
3   "status": "active",
4   "name": "Spring Sale $10 Off",
5   "discount_type": "amount_off",
6   "amount_atom_off": 1000,
7   "percent_off": 1.1,
8   "trial_days_off": 1,
9   "currency": "usd",
10   "duration": "once",
11   "duration_in_months": 1,
12   "max_redemptions": 100,
13   "redemption_count": 25,
14   "valid_from": "2024-01-15T09:30:00Z",
15   "valid_until": "2024-06-15T09:30:00Z",
16   "validity_period_days": 180,
17   "products": [
18     "prod_12345"
19   ],
20   "metadata": {},
21   "created_at": "2024-01-10T08:00:00Z",
22   "updated_at": "2024-01-15T09:30:00Z",
23   "promotion_code_count": 5,
24   "product_details": [
25     {
26       "id": "prod_12345",
27       "name": "Premium Subscription"
28     }
29   ]
30 }

Create a new coupon.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

discount_typeenumRequired

Type of discount: amount_off, percent_off, or trial_extension

namestring or nullOptional

Display name for the coupon

amount_atom_offinteger or nullOptional

Fixed amount discount in smallest currency unit (e.g., 1000 for $10.00)

percent_offdouble or nullOptional1-100

Percentage discount (1-100, up to 2 decimal places, e.g. 16.67)

trial_days_offinteger or nullOptional>=1

Number of trial days to extend

currencyenum or nullOptional

ISO 4217 currency code (required for amount_off)

durationenumOptionalDefaults to once

How long the coupon applies: once, repeating, or forever

duration_in_monthsinteger or nullOptional>=1

Number of months for repeating coupons (required if duration=repeating)

max_redemptionsinteger or nullOptional>=1

Maximum number of times this coupon can be redeemed

valid_fromdatetime or nullOptional

Date when coupon becomes valid

valid_untildatetime or nullOptional

Fixed date when coupon expires (mutually exclusive with validity_period_days)

validity_period_daysinteger or nullOptional>=1

Number of days the coupon is valid for redemption (from creation date). Mutually exclusive with valid_until.

product_idslist of stringsOptional

List of product IDs this coupon applies to. Empty list = all products.

metadatamap from strings to any or nullOptional

Arbitrary metadata

discountobject or nullOptional

Response

Successful Response

idstring

statusstring

namestring or null

discount_typestring

amount_atom_offinteger or null

percent_offdouble or null

trial_days_offinteger or null

currencyenum or null

ISO 4217 currency codes.

durationstring

duration_in_monthsinteger or null

max_redemptionsinteger or null

redemption_countinteger

valid_fromdatetime or null

valid_untildatetime or null

validity_period_daysinteger or null

productslist of strings

metadatamap from strings to any or null

created_atdatetime

updated_atdatetime

promotion_code_countintegerOptionalDefaults to 0

product_detailslist of objectsOptional

Errors

422

Unprocessable Entity Error