---
updatedAt: 2026-06-30T16:05:21.000Z
agentTools:
  projectIndex: https://docs.pelcro.com/llms.txt
---

# Create coupon

Create a new coupon.

## Overview

Create a new discount coupon for the site.

## Discount type

Provide **either** `amount_off` (fixed amount) **or** `percent_off` (percentage), but not both.

* `amount_off` requires `currency` to be set
* `percent_off` must be between 0 and 100

## Code uniqueness

The `code` must be unique within the site. It accepts only letters and numbers (alphanumeric).

## Plan restrictions

Pass an array of plan IDs in `plans` to restrict the coupon to specific plans. If set, the coupon can only be applied to subscriptions using those plans.

## Expiration

* `redeem_by` sets an expiration date (YYYY-MM-DD format, must be a future date)
* `max_redemptions` limits how many times the coupon can be used

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "core-api",
    "version": "1.88"
  },
  "servers": [
    {
      "url": "https://www.pelcro.com/api/v1/core"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer"
      },
      "sec1": {
        "type": "apiKey",
        "in": "query",
        "name": "site_id"
      }
    }
  },
  "security": [
    {
      "sec0": [],
      "sec1": []
    }
  ],
  "paths": {
    "/coupons": {
      "post": {
        "summary": "Create coupon",
        "description": "Create a new coupon.",
        "operationId": "api-core-create-coupon",
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "description": "The unique identifier of the site associated with your account."
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "default": "Bearer eyJ***"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "code",
                  "duration"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Display name of the coupon shown on invoices and receipts.",
                    "minLength": 3,
                    "maxLength": 40
                  },
                  "code": {
                    "type": "string",
                    "description": "Unique redemption code. Letters and numbers only.",
                    "minLength": 3,
                    "maxLength": 255
                  },
                  "duration": {
                    "type": "string",
                    "enum": [
                      "forever",
                      "once"
                    ],
                    "description": "How long the discount applies. \"forever\" applies indefinitely, \"once\" applies to a single invoice."
                  },
                  "amount_off": {
                    "type": "number",
                    "description": "Fixed amount discount (e.g. 5.00 for $5.00 off). Accepts up to 2 decimal places. Required if percent_off is not provided. Cannot be combined with percent_off."
                  },
                  "percent_off": {
                    "type": "number",
                    "description": "Percentage discount between 0 and 100. Required if amount_off is not provided. Cannot be combined with amount_off.",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "currency": {
                    "type": "string",
                    "description": "Three-letter ISO currency code. Required when amount_off is provided.",
                    "minLength": 3,
                    "maxLength": 3
                  },
                  "redeem_by": {
                    "type": "string",
                    "format": "date",
                    "description": "Expiration date in YYYY-MM-DD format. Must be a future date."
                  },
                  "max_redemptions": {
                    "type": "integer",
                    "description": "Maximum number of times this coupon can be redeemed.",
                    "minimum": 1
                  },
                  "plans": {
                    "type": "array",
                    "description": "Array of plan IDs this coupon is restricted to. If set, the coupon can only be used with these plans.",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Custom key-value metadata.",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "Result": {
                    "value": "{\n    \"data\": {\n        \"id\": 12,\n        \"amount_off\": null,\n        \"currency\": null,\n        \"coupon_code\": \"SAVE33\",\n        \"duration\": \"forever\",\n        \"duration_in_months\": null,\n        \"max_redemptions\": null,\n        \"expires_on\": null,\n        \"times_redeemed\": 0,\n        \"name\": \"33% Off\",\n        \"percent_off\": 33,\n        \"valid\": true,\n        \"plans\": null,\n        \"metadata\": null,\n        \"created_at\": 1620130650,\n        \"updated_at\": 1620130650\n    }\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"error\": {\n    \"status\": 400,\n    \"message\": \"Invalid request, please try again.\"\n  }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "integer",
                          "example": 400
                        },
                        "message": {
                          "type": "string",
                          "example": "Invalid request, please try again."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated.",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"error\": \"Unauthenticated.\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

# Sibling pages

* [List coupons](https://docs.pelcro.com/reference/api-core-list-coupons.md)
* [Get coupon](https://docs.pelcro.com/reference/api-core-get-coupon.md)
* [Update coupon](https://docs.pelcro.com/reference/api-core-update-coupon.md)
* [Delete coupon](https://docs.pelcro.com/reference/api-core-delete-coupon.md)