BillKitCoupons
Create coupon
Create a discount code customers can enter at checkout.
POST/v1/coupons
Parameters
| Parameter | Description |
|---|---|
| codestringrequired | The code customers enter. Stored trimmed and uppercased, so matching ignores case; must be unique on your account. At most 64 characters. |
| amount_off_centsinteger | nulloptional | Fixed amount off, in minor units of currency. Exactly one of percent_off and amount_off_cents. Between 1 and 99999999. |
| applies_to_price_idsarray of string | nulloptional | Ids of the prices the coupon can be used with. Null or empty for any price. |
| currencystring | nulloptional | Three-letter ISO 4217 currency of amount_off_cents and min_amount_cents; the coupon then applies only to prices in it. Required with either when your account has more than one currency enabled, and otherwise defaults to your one currency. At most 3 characters. |
| discount_typeenum | nulloptional | Optional. Implied by whichever of percent_off and amount_off_cents is set; must agree when sent. One of percent, fixed_amount. |
| durationenumoptional | How long the discount applies once redeemed. once discounts the first charge; repeating every charge within duration_in_months months of the first discounted charge; forever every charge. One of once, forever, repeating. Defaults to "once". |
| duration_in_monthsinteger | nulloptional | Number of months a repeating coupon applies. Required when duration is repeating. Between 1 and 120. |
| max_redemptionsinteger | nulloptional | Maximum number of times the coupon can be redeemed. Null for no limit. Between 1 and 2147483647. |
| min_amount_centsinteger | nulloptional | Minimum charge, before the discount, in minor units of currency, for the coupon to apply. Requires currency to be known. Null for no minimum. Between 0 and 99999999. |
| percent_offnumber | nulloptional | Percent off, more than 0 and at most 100, with up to two decimal places (12.5). Exactly one of percent_off and amount_off_cents. Maximum 100. |
| redeem_byinteger | nulloptional | Last time the coupon can be redeemed, in Unix seconds. Null for no deadline. Between 0 and 253402300799. |
Returns
Returns a CouponResponse object.
Errors
| Status | Cause |
|---|---|
| 400 | The request was refused (type: invalid_request_error): a required parameter is missing (parameter_missing), one failed validation (parameter_invalid) or is not one the operation takes (parameter_unknown), and param names it. |
| 401 | No credential, or one that does not authenticate. |
| 402 | The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused). |
| 403 | Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the coupons:write scope. |
| 404 | No such object in this account and mode. |
| 409 | Conflicts with the object's current state (state_conflict, or a more specific code), or an operation still in flight (operation_pending). |
| 413 | The request body is larger than the API accepts. |
| 429 | Rate limited. Retry-After says when to try again. |
| 500 | Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key. |
| 502 | The payment provider failed or did not answer. |
| 503 | Temporarily unable to serve. reason says whether the request was attempted. |
Other coupons operations
- List coupons GET /v1/coupons
- Get coupon GET /v1/coupons/{coupon_id}
- Update coupon POST /v1/coupons/{coupon_id}
- Validate coupon POST /v1/coupons/validate