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

# Create coupon API

> Create discount coupons for affiliate tracking. Percentage or fixed amount discounts with duration and redemption limits.

Create coupons that can be assigned to partners via promotion codes. When customers use these codes at checkout, sales are attributed to the partner for commission calculation.

## Endpoint

```
POST https://api.partnero.com/v1/coupons
```

## Request Body

| Parameter                         | Type    | Required | Description                                                                                                                                    |
| --------------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                            | string  | No       | Customer-facing name (defaults to `uuid_code`)                                                                                                 |
| `uuid_code`                       | string  | No       | Unique identifier (auto-generated if not provided). Allowed characters: `A-Z`, `a-z`, `0-9`, `-`, `_`. Max 255 characters                      |
| `coupon_discount_type`            | string  | Yes      | `percent` or `static`                                                                                                                          |
| `coupon_discount_amount`          | number  | Yes      | Discount value (0-100 for percent, or fixed amount)                                                                                            |
| `coupon_duration_type`            | string  | Yes      | `once`, `hours`, `days`, `months`, `years`, `lifetime`                                                                                         |
| `coupon_duration_value`           | integer | Yes\*    | Required for `hours`, `days`, `months`, `years`                                                                                                |
| `redemption_specific_date_status` | boolean | No       | Enable expiration date                                                                                                                         |
| `redemption_specific_date_value`  | date    | Yes\*    | Required if `redemption_specific_date_status` is `true`                                                                                        |
| `redemption_times_status`         | boolean | No       | Enable redemption limit                                                                                                                        |
| `redemption_times_value`          | integer | Yes\*    | Required if `redemption_times_status` is `true`                                                                                                |
| `promotion_codes`                 | array   | No       | Array of [promotion codes](/api-reference/promotion-codes/create) to create alongside the coupon                                               |
| `metadata`                        | object  | No       | Custom key-value pairs                                                                                                                         |
| `sync`                            | object  | No       | Optional object to push the coupon to a connected integration on creation. See [Syncing to a payment provider](#syncing-to-a-payment-provider) |
| `sync.provider`                   | string  | No       | One of `stripe`, `shopify`, `woocommerce`, `paddle`. Must be a provider that is currently connected to the program                             |

## Request

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/coupons' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "PARTNERO25",
    "uuid_code": "coupon_123",
    "coupon_discount_type": "percent",
    "coupon_discount_amount": 25,
    "coupon_duration_type": "months",
    "coupon_duration_value": 11,
    "redemption_times_status": true,
    "redemption_times_value": 24
  }'
```

## Syncing to a payment provider

If you pass a `sync` object with a `provider`, Partnero will create the coupon in the connected integration.

| Provider value | Integration |
| -------------- | ----------- |
| `stripe`       | Stripe      |
| `shopify`      | Shopify     |
| `woocommerce`  | WooCommerce |
| `paddle`       | Paddle      |

Omit `sync` (or send `null`) if you don't want the coupon pushed to any third-party system.

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/coupons' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "PARTNERO25",
    "uuid_code": "coupon_123",
    "sync": { "provider": "stripe" },
    "coupon_discount_type": "percent",
    "coupon_discount_amount": 25,
    "coupon_duration_type": "months",
    "coupon_duration_value": 11,
    "redemption_times_status": true,
    "redemption_times_value": 24
  }'
```

On a successful sync the response includes:

```json theme={null}
{
  "synchronization_enabled": true,
  "synchronization_successful": true,
  "synchronization_message": "The coupon was successfully created in Stripe."
}
```

If the requested provider is not connected to the program, the request is rejected with `422` and:

```json theme={null}
{
  "message": "stripe is not connected for this program.",
  "errors": {
    "sync.provider": ["stripe is not connected for this program."]
  }
}
```

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "name": "PARTNERO25",
      "uuid_code": "coupon_123",
      "active": true,
      "coupon_discount_type": "percent",
      "coupon_discount_amount": 25,
      "coupon_duration_type": "months",
      "coupon_duration_value": 11,
      "redemption_specific_date_status": false,
      "redemption_specific_date_value": null,
      "redemption_times_status": true,
      "redemption_times_value": 24,
      "metadata": [],
      "additional_info": [],
      "times_redeemed": 0,
      "created_at": "2025-05-07T17:43:26.000000Z",
      "updated_at": "2025-05-07T17:43:26.000000Z",
      "deleted_at": null
    },
    "status": 1,
    "message": "Coupon created in the app successfully.",
    "synchronization_enabled": false,
    "synchronization_successful": false,
    "synchronization_message": ""
  }
  ```
</ResponseExample>

<Note>
  Coupons can be automatically synced to Stripe, Shopify, WooCommerce, or Paddle on creation. See [Syncing to a payment provider](#syncing-to-a-payment-provider).
</Note>