Coupon Details

A coupon has either a percent_off or an amount_off and currency. If you set an amount_off, then that amount will be subtracted from any invoice’s subtotal.

Coupon Parameters

This section describes the parameters required to define a coupon. Each parameter includes its type, format, and specific usage notes.

1. Discount ID (`discount_id`)

Type: string
Description: An ID that refers to a coupon when applying to a customer's subscription.
Required: Optional
Format: Alphanumeric and Special Characters
Min Length: 3 characters
Max Length: 191 characters
Example:
- mycoupon_1
- dc_c7cc1e9c (if PAYARC generated one)
Note: Users can create a custom coupon ID or PAYARC will automatically generate one.

2. Name (`name`)

Type: string
Description: Name of the coupon.
Required: Yes
Format: Alphanumeric and Special Characters
Min Length: 5 characters
Max Length: 50 characters
Example: mycouponname

3. Currency (`currency`)

Type: string
Description: Three-letter ISO currency code, in lowercase.
Required: Yes
Format: Alphabetic
Enumeration:
- usd

4. Duration (`duration`)

Type: string
Description: The duration for which the subscription invoices are discounted from the time a coupon is redeemed or applied.
Required: Yes
Format: Alphabetic
Enumeration:
- once: Discount applied only for one invoice.
- repeating: Discount applied on invoices for specified duration of months (duration_in_months).
- forever: Discount applied until subscription is cancelled.

5. Duration in Months (`duration_in_months`)

Type: integer
Description: The duration for which the subscription invoices are discounted from the time a coupon is redeemed or applied.
Required: Conditional
Format: Numeric
Min Month Value: 1 month
Max Month Value: 36 months
Note: Should be passed only when duration is marked as repeating.

6. Maximum Redemptions (`max_redemptions`)

Type: integer
Description: Maximum number of times a coupon can be used on subscriptions.
Required: Optional
Format: Numeric
Min Value: 1
Max Value: 99

7. Percent Off (`percent_off`)

Type: integer
Description: A number that represents the discount that will be applied when a coupon is used.
Required: Conditional
Format: Numeric
Min Value: 0.1%
Max Value: 99.99%
Note: Should be passed only when amount_off is not passed.

8. Amount Off (`amount_off`)

Type: integer
Description: A number that represents the amount to be subtracted from an invoice total.
Required: Conditional
Format: Numeric
Min Value: 1 cent
Max Value: $10,000,000 (in cents)
Example:
- 9 would be $0.09
- 10000000 would be $100,000.00
Note: Should be passed only when percent_off is not passed.

9. Redeem By (`redeem_by`)

Type: string
Description: Timestamp specifying the last time at which the coupon can be redeemed. After the redeem_by date, the coupon can no longer be applied to new subscriptions.
Required: Optional
Format: Date: YYYY-MM-DD