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

# Create Coupon

> The "Create Coupon" API allows you to create a new promotional coupon with customizable parameters such as discount amount, validity period, usage limits, and applicable products. Use this endpoint to

The "Create Coupon" API allows you to create a new promotional coupon with customizable parameters such as discount amount, validity period, usage limits, and applicable products. Use this endpoint to set up promotional offers and special discounts for your customers.

```http theme={null}
POST https://services.leadconnectorhq.com/payments/coupon
```

## Autorización

<ParamField header="Authorization" type="string" required>
  Bearer token generado desde el portal Leadway. Ver [Autenticación](/authentication).
</ParamField>

<ParamField header="Version" type="string" required default="2021-07-28">
  Versión de la API.
</ParamField>

## Body

<ParamField body="altId" type="string" required default="BQdAwxa0ky1iK2sstLGJ">
  Account Id
</ParamField>

<ParamField body="altType" type="string" required default="account">
  Alt Type Posibles valores: 'account'
</ParamField>

<ParamField body="name" type="string" required default="New Year Sale">
  Coupon Name
</ParamField>

<ParamField body="code" type="string" required default="LEVELUPDAY2022">
  Coupon Code
</ParamField>

<ParamField body="discountType" type="string" required default="amount">
  Discount Type Posibles valores: 'percentage', 'amount'
</ParamField>

<ParamField body="discountValue" type="number" required default="10">
  Discount Value
</ParamField>

<ParamField body="startDate" type="string" required default="2023-01-01T22:45:00.000Z">
  Start date in YYYY-MM-DDTHH:mm:ssZ format
</ParamField>

<ParamField body="endDate" type="string" default="2023-01-31T22:45:00.000Z">
  End date in YYYY-MM-DDTHH:mm:ssZ format
</ParamField>

<ParamField body="usageLimit" type="number" default="10">
  Max number of times coupon can be used
</ParamField>

<ParamField body="productIds" type="string[]">
  Product Ids
</ParamField>

<ParamField body="applyToFuturePayments" type="boolean" default="True">
  Is Coupon applicable on upcoming subscription transactions
</ParamField>

<ParamField body="applyToFuturePaymentsConfig" type="object">
  If coupon is applicable on upcoming subscription transactions, how many months should it be applicable for a subscription
</ParamField>

<ParamField body="limitPerCustomer" type="boolean" default="True">
  Limits whether a coupon can be redeemed only once per customer.
</ParamField>

## Respuestas

<Accordion title="201 - Successful response">
  <ResponseField name="_id" type="string" required default="67f6c132d9485f9dacd5f123">
    Unique MongoDB identifier for the coupon
  </ResponseField>

  <ResponseField name="usageCount" type="number" required default="12">
    Number of times the coupon has been used
  </ResponseField>

  <ResponseField name="limitPerCustomer" type="number" required default="5">
    Maximum number of times a customer can use this coupon (0 for unlimited)
  </ResponseField>

  <ResponseField name="altId" type="string" required default="79t07PzK8Tvf73d12312">
    Account Id
  </ResponseField>

  <ResponseField name="altType" type="string" required default="account">
    Type of entity
  </ResponseField>

  <ResponseField name="name" type="string" required default="NEWT6">
    Display name of the coupon
  </ResponseField>

  <ResponseField name="code" type="string" required default="NEWT6">
    Redemption code for the coupon
  </ResponseField>

  <ResponseField name="discountType" type="string" required default="percentage">
    Type of discount (percentage or amount) Posibles valores: 'percentage', 'amount'
  </ResponseField>

  <ResponseField name="discountValue" type="number" required default="25">
    Value of the discount (percentage or fixed amount)
  </ResponseField>

  <ResponseField name="status" type="string" required default="scheduled">
    Current status of the coupon Posibles valores: 'scheduled', 'active', 'expired'
  </ResponseField>

  <ResponseField name="startDate" type="string" required default="2025-04-30T18:30:00.000Z">
    Date when the coupon becomes active
  </ResponseField>

  <ResponseField name="endDate" type="string" default="2025-05-30T18:30:00.000Z">
    End date when the coupon expires
  </ResponseField>

  <ResponseField name="applyToFuturePayments" type="boolean" required default="True">
    Indicates if the coupon applies to future recurring payments
  </ResponseField>

  <ResponseField name="applyToFuturePaymentsConfig" type="object" required>
    Configuration for how the coupon applies to future payments
  </ResponseField>

  <ResponseField name="userId" type="string" default="q0m15dTLGeiGOXG123123">
    User ID associated with the coupon (if applicable)
  </ResponseField>

  <ResponseField name="createdAt" type="string" required default="2025-04-09T18:49:22.026Z">
    Creation timestamp
  </ResponseField>

  <ResponseField name="updatedAt" type="string" required default="2025-04-09T18:49:22.026Z">
    Last update timestamp
  </ResponseField>

  <ResponseField name="traceId" type="string" required default="c667b18d-8f5e-44cf-a914">
    Unique identifier for tracing this API request
  </ResponseField>

  ```json theme={null}
  {
    "_id": "67f6c132d9485f9dacd5f123",
    "usageCount": 12,
    "limitPerCustomer": 5,
    "altId": "79t07PzK8Tvf73d12312",
    "altType": "account",
    "name": "NEWT6",
    "code": "NEWT6",
    "discountType": "percentage",
    "discountValue": 25,
    "status": "scheduled",
    "startDate": "2025-04-30T18:30:00.000Z",
    "endDate": "2025-05-30T18:30:00.000Z",
    "applyToFuturePayments": true,
    "userId": "q0m15dTLGeiGOXG123123",
    "createdAt": "2025-04-09T18:49:22.026Z",
    "updatedAt": "2025-04-09T18:49:22.026Z",
    "traceId": "c667b18d-8f5e-44cf-a914"
  }
  ```
</Accordion>

<Accordion title="422 - Unprocessable Entity">
  ```json theme={null}
  {}
  ```
</Accordion>

## Ejemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://services.leadconnectorhq.com/payments/coupon' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Version: 2021-07-28' \
    -H 'Content-Type: application/json' \
    -d '{
    "altId": "BQdAwxa0ky1iK2sstLGJ",
    "altType": "account",
    "name": "New Year Sale",
    "code": "LEVELUPDAY2022",
    "discountType": "amount",
    "discountValue": 10,
    "startDate": "2023-01-01T22:45:00.000Z",
    "endDate": "2023-01-31T22:45:00.000Z",
    "usageLimit": 10,
    "productIds": [
      "6241712be68f7a98102ba272"
    ],
    "applyToFuturePayments": true,
    "applyToFuturePaymentsConfig": [
      {
        "type": "fixed",
        "duration": 5,
        "durationType": "months"
      },
      {
        "type": "forever"
      }
    ],
    "limitPerCustomer": true
  }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://services.leadconnectorhq.com/payments/coupon', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LEADWAY_TOKEN}`,
      Version: '2021-07-28',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({"altId": "BQdAwxa0ky1iK2sstLGJ", "altType": "account", "name": "New Year Sale", "code": "LEVELUPDAY2022", "discountType": "amount", "discountValue": 10, "startDate": "2023-01-01T22:45:00.000Z", "endDate": "2023-01-31T22:45:00.000Z", "usageLimit": 10, "productIds": ["6241712be68f7a98102ba272"], "applyToFuturePayments": true, "applyToFuturePaymentsConfig": [{"type": "fixed", "duration": 5, "durationType": "months"}, {"type": "forever"}], "limitPerCustomer": true}),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import os, requests
  response = requests.request(
      'POST',
      'https://services.leadconnectorhq.com/payments/coupon',
      headers={
          'Authorization': f"Bearer {os.environ['LEADWAY_TOKEN']}",
          'Version': '2021-07-28',
          'Content-Type': 'application/json',
      },
      json={"altId": "BQdAwxa0ky1iK2sstLGJ", "altType": "account", "name": "New Year Sale", "code": "LEVELUPDAY2022", "discountType": "amount", "discountValue": 10, "startDate": "2023-01-01T22:45:00.000Z", "endDate": "2023-01-31T22:45:00.000Z", "usageLimit": 10, "productIds": ["6241712be68f7a98102ba272"], "applyToFuturePayments": true, "applyToFuturePaymentsConfig": [{"type": "fixed", "duration": 5, "durationType": "months"}, {"type": "forever"}], "limitPerCustomer": true},
  )
  data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://services.leadconnectorhq.com/payments/coupon');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('LEADWAY_TOKEN'),
          'Version: 2021-07-28',
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode({'altId': 'BQdAwxa0ky1iK2sstLGJ', 'altType': 'account', 'name': 'New Year Sale', 'code': 'LEVELUPDAY2022', 'discountType': 'amount', 'discountValue': 10, 'startDate': '2023-01-01T22:45:00.000Z', 'endDate': '2023-01-31T22:45:00.000Z', 'usageLimit': 10, 'productIds': ['6241712be68f7a98102ba272'], 'applyToFuturePayments': true, 'applyToFuturePaymentsConfig': [{'type': 'fixed', 'duration': 5, 'durationType': 'months'}, {'type': 'forever'}], 'limitPerCustomer': true}),
  ]);
  $data = json_decode(curl_exec($ch), true);
  ```
</CodeGroup>