Create Coupon

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",
    "program_id": "prg_789ghi",
    "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
  }
}

POST

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",
    "program_id": "prg_789ghi",
    "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_months required when duration is repeating
All providers: currency required when discount_type is fixed

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 invoices
once: Discount applies only to the first invoice
repeating: 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 responses

object

The created coupon object.

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

The ID of the affiliate program this coupon belongs to

string

Type of discount: percentage or fixed

number

The discount amount

string

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

integer | 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.

The promo code ID at the primary payment provider.

array

Array of provider-specific coupon records. Each record contains:

provider (string): The payment provider name
provider_coupon_id (string): The coupon ID at this provider
provider_promo_code_id (string): The promo code ID at this provider
created_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",
    "program_id": "prg_789ghi",
    "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_FOUND

Returned when the affiliate has no program partnership or the program has no payment provider configured. Error code: VALIDATION_ERROR

Returned 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_ERROR

Returned when the payment provider fails to create the coupon.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Response

Error Responses

​Body Parameters

​Response

​Error Responses

Body Parameters

Response

Error Responses