> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Coupon

> Generate a new promotional coupon for an affiliate

Create a new promotional coupon for an affiliate. The coupon is created at your payment provider and linked to the affiliate in Affonso.

<Warning>
  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`
</Warning>

## Body Parameters

<ParamField body="affiliate_id" type="string" required>
  The ID of the affiliate who will own this coupon.
</ParamField>

<ParamField body="code" type="string" required>
  The coupon code. Must be 1-50 characters, alphanumeric characters and hyphens only. Will be converted to uppercase.
</ParamField>

<ParamField body="discount_type" type="string" required>
  Type of discount to apply. Valid values: `percentage`, `fixed`.
</ParamField>

<ParamField body="discount_value" type="number" required>
  The discount amount. For `percentage`: value between 0-100. For `fixed`: the discount amount in the specified currency.
</ParamField>

<ParamField body="duration" type="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
</ParamField>

<ParamField body="duration_in_months" type="integer">
  Number of months the discount repeats. **Required when `duration` is `repeating`**.
</ParamField>

<ParamField body="currency" type="string">
  Three-letter currency code (e.g., `USD`, `EUR`, `GBP`). **Required when `discount_type` is `fixed`**.
</ParamField>

<ParamField body="product_ids" type="array">
  Array of product IDs to restrict this coupon to. Leave empty or omit to apply to all products.
</ParamField>

## Response

The response includes the created coupon object.

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="object">
  The created coupon object.

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the coupon
    </ResponseField>

    <ResponseField name="code" type="string">
      The coupon code (uppercase)
    </ResponseField>

    <ResponseField name="affiliate_id" type="string">
      The ID of the affiliate who owns this coupon
    </ResponseField>

    <ResponseField name="program_id" type="string">
      The ID of the affiliate program this coupon belongs to
    </ResponseField>

    <ResponseField name="discount_type" type="string">
      Type of discount: `percentage` or `fixed`
    </ResponseField>

    <ResponseField name="discount_value" type="number">
      The discount amount
    </ResponseField>

    <ResponseField name="duration" type="string">
      How long the discount applies: `forever`, `once`, or `repeating`
    </ResponseField>

    <ResponseField name="duration_in_months" type="integer | null">
      Number of months the discount repeats (only applicable when duration is `repeating`)
    </ResponseField>

    <ResponseField name="currency" type="string | null">
      Three-letter currency code (only applicable when discount\_type is `fixed`)
    </ResponseField>

    <ResponseField name="product_ids" type="array">
      Array of product IDs this coupon is restricted to
    </ResponseField>

    <ResponseField name="provider" type="string | null">
      The primary payment provider for this coupon (e.g., `stripe`, `dodo`, `creem`).
    </ResponseField>

    <ResponseField name="provider_coupon_id" type="string | null">
      The coupon ID at the primary payment provider.
    </ResponseField>

    <ResponseField name="provider_promo_code_id" type="string | null">
      The promo code ID at the primary payment provider.
    </ResponseField>

    <ResponseField name="provider_records" type="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
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the coupon was created
    </ResponseField>

    <ResponseField name="updated_at" type="string | null">
      ISO 8601 timestamp of when the coupon was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Percentage Discount theme={null}
  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"
    }'
  ```

  ```bash Fixed Discount theme={null}
  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"
    }'
  ```

  ```bash Repeating Discount theme={null}
  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
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseField name="404 Not Found">
  Returned when the specified affiliate does not exist or does not belong to your team.
  Error code: `NOT_FOUND`
</ResponseField>

<ResponseField name="400 Bad Request">
  Returned when the affiliate has no program partnership or the program has no payment provider configured.
  Error code: `VALIDATION_ERROR`
</ResponseField>

<ResponseField name="409 Conflict">
  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`
</ResponseField>

<ResponseField name="502 Bad Gateway">
  Returned when the payment provider fails to create the coupon.
</ResponseField>