# Create Coupon

POST https://services.leadconnectorhq.com/payments/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 set up promotional offers and special discounts for your customers.

## Authentication

Send `Authorization: Bearer <token>` using:

- **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `payments/coupons.write`

## Parameters

### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Version` | string | Yes | API Version |

## OpenAPI Specification

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "LeadConnector API",
    "version": "v3"
  },
  "servers": [
    {
      "url": "https://services.leadconnectorhq.com"
    }
  ],
  "paths": {
    "/payments/coupon": {
      "post": {
        "summary": "Create Coupon",
        "operationId": "createCoupon",
        "description": "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.",
        "parameters": [
          {
            "name": "Version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "v3"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCouponParams"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateCouponResponseDto"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Location-Access": [
              "payments/coupons.write"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account.",
        "type": "http"
      },
      "Agency-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
        "type": "http"
      },
      "Agency-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency.",
        "type": "http"
      }
    },
    "schemas": {
      "CreateCouponParams": {
        "type": "object",
        "properties": {
          "altId": {
            "type": "string",
            "description": "Location Id",
            "example": "BQdAwxa0ky1iK2sstLGJ"
          },
          "altType": {
            "type": "string",
            "description": "Alt Type",
            "enum": [
              "location"
            ],
            "example": "location"
          },
          "name": {
            "type": "string",
            "description": "Coupon Name",
            "example": "New Year Sale"
          },
          "code": {
            "type": "string",
            "description": "Coupon Code",
            "example": "LEVELUPDAY2022"
          },
          "discountType": {
            "type": "string",
            "description": "Discount Type",
            "enum": [
              "percentage",
              "amount"
            ],
            "example": "amount"
          },
          "discountValue": {
            "type": "number",
            "description": "Discount Value",
            "example": 10
          },
          "startDate": {
            "type": "string",
            "description": "Start date in YYYY-MM-DDTHH:mm:ssZ format",
            "example": "2023-01-01T22:45:00.000Z"
          },
          "endDate": {
            "type": "string",
            "description": "End date in YYYY-MM-DDTHH:mm:ssZ format",
            "example": "2023-01-31T22:45:00.000Z"
          },
          "usageLimit": {
            "type": "number",
            "description": "Max number of times coupon can be used",
            "example": 10
          },
          "productIds": {
            "description": "Product Ids",
            "example": [
              "6241712be68f7a98102ba272"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "priceIds": {
            "description": "Price Ids",
            "example": [
              "6241712be68f7a98102ba272"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "variantIds": {
            "description": "Variant Ids",
            "example": [
              "6241712be68f7a98102ba272"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "applyToFuturePayments": {
            "type": "boolean",
            "example": true,
            "default": true,
            "description": "Is Coupon applicable on upcoming subscription transactions"
          },
          "applyToFuturePaymentsConfig": {
            "example": [
              {
                "type": "fixed",
                "duration": 5,
                "durationType": "months"
              },
              {
                "type": "forever"
              }
            ],
            "default": {
              "type": "forever"
            },
            "description": "If coupon is applicable on upcoming subscription transactions, how many months should it be applicable for a subscription",
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "description": "Type of the config",
                    "example": "forever | fixed",
                    "enum": [
                      "forever",
                      "fixed"
                    ]
                  },
                  "duration": {
                    "type": "number",
                    "description": "Duration the coupon to be applied in a subscription",
                    "example": 5
                  },
                  "durationType": {
                    "type": "string",
                    "description": "Type of the duration",
                    "example": "months",
                    "enum": [
                      "months"
                    ]
                  }
                },
                "required": [
                  "type",
                  "duration",
                  "durationType"
                ],
                "title": "ApplyToFuturePaymentsConfig"
              }
            ]
          },
          "limitPerCustomer": {
            "type": "boolean",
            "example": true,
            "default": false,
            "description": "Limits whether a coupon can be redeemed only once per customer."
          }
        },
        "required": [
          "altId",
          "altType",
          "name",
          "code",
          "discountType",
          "discountValue",
          "startDate"
        ],
        "title": "CreateCouponParams"
      },
      "CreateCouponResponseDto": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Unique MongoDB identifier for the coupon",
            "example": "67f6c132d9485f9dacd5f123"
          },
          "usageCount": {
            "type": "number",
            "description": "Number of times the coupon has been used",
            "example": 12
          },
          "limitPerCustomer": {
            "type": "number",
            "description": "Maximum number of times a customer can use this coupon (0 for unlimited)",
            "example": 5
          },
          "altId": {
            "type": "string",
            "description": "Location Id",
            "example": "79t07PzK8Tvf73d12312"
          },
          "altType": {
            "type": "string",
            "description": "Type of entity",
            "example": "location"
          },
          "name": {
            "type": "string",
            "description": "Display name of the coupon",
            "example": "NEWT6"
          },
          "code": {
            "type": "string",
            "description": "Redemption code for the coupon",
            "example": "NEWT6"
          },
          "discountType": {
            "type": "string",
            "description": "Type of discount (percentage or amount)",
            "example": "percentage",
            "enum": [
              "percentage",
              "amount"
            ]
          },
          "discountValue": {
            "type": "number",
            "description": "Value of the discount (percentage or fixed amount)",
            "example": 25
          },
          "status": {
            "type": "string",
            "description": "Current status of the coupon",
            "example": "scheduled",
            "enum": [
              "scheduled",
              "active",
              "expired"
            ]
          },
          "startDate": {
            "type": "string",
            "description": "Date when the coupon becomes active",
            "example": "2025-04-30T18:30:00.000Z"
          },
          "endDate": {
            "type": "string",
            "description": "End date when the coupon expires",
            "example": "2025-05-30T18:30:00.000Z"
          },
          "applyToFuturePayments": {
            "type": "boolean",
            "description": "Indicates if the coupon applies to future recurring payments",
            "example": true
          },
          "applyToFuturePaymentsConfig": {
            "description": "Configuration for how the coupon applies to future payments",
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "description": "Type of future payments configuration",
                    "example": "fixed",
                    "enum": [
                      "forever",
                      "fixed"
                    ]
                  },
                  "duration": {
                    "type": "number",
                    "description": "Duration value for fixed type configurations",
                    "example": 3
                  },
                  "durationType": {
                    "type": "string",
                    "description": "Duration type for fixed configurations (e.g. months)",
                    "example": "months"
                  }
                },
                "required": [
                  "type"
                ],
                "title": "ApplyToFuturePaymentsConfigDto"
              }
            ]
          },
          "userId": {
            "type": "string",
            "description": "User ID associated with the coupon (if applicable)",
            "example": "q0m15dTLGeiGOXG123123"
          },
          "createdAt": {
            "type": "string",
            "description": "Creation timestamp",
            "example": "2025-04-09T18:49:22.026Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "Last update timestamp",
            "example": "2025-04-09T18:49:22.026Z"
          },
          "traceId": {
            "type": "string",
            "description": "Unique identifier for tracing this API request",
            "example": "c667b18d-8f5e-44cf-a914"
          }
        },
        "required": [
          "_id",
          "usageCount",
          "limitPerCustomer",
          "altId",
          "altType",
          "name",
          "code",
          "discountType",
          "discountValue",
          "status",
          "startDate",
          "applyToFuturePayments",
          "applyToFuturePaymentsConfig",
          "createdAt",
          "updatedAt",
          "traceId"
        ],
        "title": "CreateCouponResponseDto"
      },
      "UnprocessableDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 422
          },
          "message": {
            "example": [
              "Unprocessable Entity"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string",
            "example": "Unprocessable Entity"
          }
        },
        "title": "UnprocessableDTO"
      }
    }
  }
}
```

## Code Examples

**cURL**

```bash
curl -L -X POST 'https://services.leadconnectorhq.com/payments/coupon' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Version: v3' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "altId": "BQdAwxa0ky1iK2sstLGJ",
  "altType": "location",
  "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"
  ],
  "priceIds": [
    "6241712be68f7a98102ba272"
  ],
  "variantIds": [
    "6241712be68f7a98102ba272"
  ],
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": [
    {
      "type": "fixed",
      "duration": 5,
      "durationType": "months"
    },
    {
      "type": "forever"
    }
  ],
  "limitPerCustomer": true
}'
```

**Node.js**

```javascript
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    Version: 'v3',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "altId": "BQdAwxa0ky1iK2sstLGJ",
      "altType": "location",
      "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"
      ],
      "priceIds": [
        "6241712be68f7a98102ba272"
      ],
      "variantIds": [
        "6241712be68f7a98102ba272"
      ],
      "applyToFuturePayments": true,
      "applyToFuturePaymentsConfig": [
        {
          "type": "fixed",
          "duration": 5,
          "durationType": "months"
        },
        {
          "type": "forever"
        }
      ],
      "limitPerCustomer": true
  })
};

try {
  const response = await fetch('https://services.leadconnectorhq.com/payments/coupon', options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**Python**

```python
import requests

url = "https://services.leadconnectorhq.com/payments/coupon"

headers = {
    "Authorization": "Bearer <TOKEN>",
    "Version": "v3"
}

payload = {
    "altId": "BQdAwxa0ky1iK2sstLGJ",
    "altType": "location",
    "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"
    ],
    "priceIds": [
        "6241712be68f7a98102ba272"
    ],
    "variantIds": [
        "6241712be68f7a98102ba272"
    ],
    "applyToFuturePayments": true,
    "applyToFuturePaymentsConfig": [
        {
            "type": "fixed",
            "duration": 5,
            "durationType": "months"
        },
        {
            "type": "forever"
        }
    ],
    "limitPerCustomer": true
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

**PHP**

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://services.leadconnectorhq.com/payments/coupon',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Version: v3',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "altId": "BQdAwxa0ky1iK2sstLGJ",
  "altType": "location",
  "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"
  ],
  "priceIds": [
    "6241712be68f7a98102ba272"
  ],
  "variantIds": [
    "6241712be68f7a98102ba272"
  ],
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": [
    {
      "type": "fixed",
      "duration": 5,
      "durationType": "months"
    },
    {
      "type": "forever"
    }
  ],
  "limitPerCustomer": true
}',
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

**Java**

```java
HttpResponse<String> response = Unirest
  .post("https://services.leadconnectorhq.com/payments/coupon")
  .header("Authorization", "Bearer <TOKEN>")
  .header("Version", "v3")
  .header("Content-Type", "application/json")
  .body("{\"altId\":\"BQdAwxa0ky1iK2sstLGJ\",\"altType\":\"location\",\"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\"],\"priceIds\":[\"6241712be68f7a98102ba272\"],\"variantIds\":[\"6241712be68f7a98102ba272\"],\"applyToFuturePayments\":true,\"applyToFuturePaymentsConfig\":[{\"type\":\"fixed\",\"duration\":5,\"durationType\":\"months\"},{\"type\":\"forever\"}],\"limitPerCustomer\":true}")
  .asString();
```

**Go**

```go
package main

import (
  "fmt"
  "net/http"
  "io"
  "strings"
)

func main() {
  url := "https://services.leadconnectorhq.com/payments/coupon"
  payload := strings.NewReader(`{
  "altId": "BQdAwxa0ky1iK2sstLGJ",
  "altType": "location",
  "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"
  ],
  "priceIds": [
    "6241712be68f7a98102ba272"
  ],
  "variantIds": [
    "6241712be68f7a98102ba272"
  ],
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": [
    {
      "type": "fixed",
      "duration": 5,
      "durationType": "months"
    },
    {
      "type": "forever"
    }
  ],
  "limitPerCustomer": true
}`)
  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Version", "v3")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

**Ruby**

```ruby
require 'uri'
require 'net/http'

url = URI("https://services.leadconnectorhq.com/payments/coupon")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <TOKEN>"
request["Version"] = "v3"
request["Content-Type"] = "application/json"
request.body = '{
  "altId": "BQdAwxa0ky1iK2sstLGJ",
  "altType": "location",
  "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"
  ],
  "priceIds": [
    "6241712be68f7a98102ba272"
  ],
  "variantIds": [
    "6241712be68f7a98102ba272"
  ],
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": [
    {
      "type": "fixed",
      "duration": 5,
      "durationType": "months"
    },
    {
      "type": "forever"
    }
  ],
  "limitPerCustomer": true
}'

response = http.request(request)
puts response.read_body
```

**PowerShell**

```powershell
$headers = @{
  "Authorization" = "Bearer <TOKEN>"
  "Version" = "v3"
}

$body = '{
  "altId": "BQdAwxa0ky1iK2sstLGJ",
  "altType": "location",
  "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"
  ],
  "priceIds": [
    "6241712be68f7a98102ba272"
  ],
  "variantIds": [
    "6241712be68f7a98102ba272"
  ],
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": [
    {
      "type": "fixed",
      "duration": 5,
      "durationType": "months"
    },
    {
      "type": "forever"
    }
  ],
  "limitPerCustomer": true
}'

$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/payments/coupon' -Method 'POST' -Headers $headers -Body $body -ContentType 'application/json'
$response | ConvertTo-Json
```