curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "SAVE25",
"discount_type": "percentage",
"discount_value": 25,
"duration": "forever"
}'
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "10OFF",
"discount_type": "fixed",
"discount_value": 10,
"duration": "once",
"currency": "USD"
}'
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "3MONTHS",
"discount_type": "percentage",
"discount_value": 15,
"duration": "repeating",
"duration_in_months": 3
}'
{
"success": true,
"data": {
"id": "cpn_abc123",
"code": "SAVE25",
"affiliate_id": "aff_123",
"discount_type": "percentage",
"discount_value": 25,
"duration": "forever",
"duration_in_months": null,
"currency": null,
"product_ids": [],
"provider": "stripe",
"provider_coupon_id": "promo_abc123",
"provider_promo_code_id": "pc_abc123",
"provider_records": [
{
"provider": "stripe",
"provider_coupon_id": "promo_abc123",
"provider_promo_code_id": "pc_abc123",
"created_at": "2024-01-15T10:30:00Z"
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": null
}
}
Coupons
Create Coupon
Generate a new promotional coupon for an affiliate
POST
/
v1
/
coupons
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "SAVE25",
"discount_type": "percentage",
"discount_value": 25,
"duration": "forever"
}'
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "10OFF",
"discount_type": "fixed",
"discount_value": 10,
"duration": "once",
"currency": "USD"
}'
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "3MONTHS",
"discount_type": "percentage",
"discount_value": 15,
"duration": "repeating",
"duration_in_months": 3
}'
{
"success": true,
"data": {
"id": "cpn_abc123",
"code": "SAVE25",
"affiliate_id": "aff_123",
"discount_type": "percentage",
"discount_value": 25,
"duration": "forever",
"duration_in_months": null,
"currency": null,
"product_ids": [],
"provider": "stripe",
"provider_coupon_id": "promo_abc123",
"provider_promo_code_id": "pc_abc123",
"provider_records": [
{
"provider": "stripe",
"provider_coupon_id": "promo_abc123",
"provider_promo_code_id": "pc_abc123",
"created_at": "2024-01-15T10:30:00Z"
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": null
}
}
Create a new promotional coupon for an affiliate. The coupon is created at your payment provider and linked to the affiliate in Affonso.
Coupon creation rules vary by payment provider:
- DODO: Only supports percentage discounts
- CREEM: Requires at least one product_id
- All providers:
duration_in_monthsrequired whendurationisrepeating - All providers:
currencyrequired whendiscount_typeisfixed
Body Parameters
string
required
The ID of the affiliate who will own this coupon.
string
required
The coupon code. Must be 1-50 characters, alphanumeric characters and hyphens only. Will be converted to uppercase.
string
required
Type of discount to apply. Valid values:
percentage, fixed.number
required
The discount amount. For
percentage: value between 0-100. For fixed: the discount amount in the specified currency.string
required
How long the discount applies. Valid values:
forever: Discount applies to all future invoicesonce: Discount applies only to the first invoicerepeating: Discount repeats for a specified number of months
integer
Number of months the discount repeats. Required when
duration is repeating.string
Three-letter currency code (e.g.,
USD, EUR, GBP). Required when discount_type is fixed.array
Array of product IDs to restrict this coupon to. Leave empty or omit to apply to all products.
Response
The response includes the created coupon object.boolean
Always
true for successful responsesobject
The created coupon object.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the coupon
string
The coupon code (uppercase)
string
The ID of the affiliate who owns this coupon
string
Type of discount:
percentage or fixednumber
The discount amount
string
How long the discount applies:
forever, once, or repeatinginteger | null
Number of months the discount repeats (only applicable when duration is
repeating)string | null
Three-letter currency code (only applicable when discount_type is
fixed)array
Array of product IDs this coupon is restricted to
string | null
The primary payment provider for this coupon (e.g.,
stripe, dodo, creem).string | null
The coupon ID at the primary payment provider.
string | null
The promo code ID at the primary payment provider.
array
Array of provider-specific coupon records. Each record contains:
provider(string): The payment provider nameprovider_coupon_id(string): The coupon ID at this providerprovider_promo_code_id(string): The promo code ID at this providercreated_at(string): ISO 8601 timestamp of when the provider record was created
string
ISO 8601 timestamp of when the coupon was created
string | null
ISO 8601 timestamp of when the coupon was last updated
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "SAVE25",
"discount_type": "percentage",
"discount_value": 25,
"duration": "forever"
}'
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "10OFF",
"discount_type": "fixed",
"discount_value": 10,
"duration": "once",
"currency": "USD"
}'
curl -X POST "https://api.affonso.io/v1/coupons" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"affiliate_id": "aff_123",
"code": "3MONTHS",
"discount_type": "percentage",
"discount_value": 15,
"duration": "repeating",
"duration_in_months": 3
}'
{
"success": true,
"data": {
"id": "cpn_abc123",
"code": "SAVE25",
"affiliate_id": "aff_123",
"discount_type": "percentage",
"discount_value": 25,
"duration": "forever",
"duration_in_months": null,
"currency": null,
"product_ids": [],
"provider": "stripe",
"provider_coupon_id": "promo_abc123",
"provider_promo_code_id": "pc_abc123",
"provider_records": [
{
"provider": "stripe",
"provider_coupon_id": "promo_abc123",
"provider_promo_code_id": "pc_abc123",
"created_at": "2024-01-15T10:30:00Z"
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": null
}
}
Error Responses
Returned when the specified affiliate does not exist or does not belong to your team.
Error code:
NOT_FOUNDReturned when the affiliate has no program partnership or the program has no payment provider configured.
Error code:
VALIDATION_ERRORReturned when a coupon with the same code already exists in the program, or when the affiliate already has a coupon for this program.
Error code:
DUPLICATE_ERRORReturned when the payment provider fails to create the coupon.
Was this page helpful?