# Create a coupon

Creates a coupon.

Endpoint: POST /coupons
Version: latest
Security: SecretApiKey, JWT, ApplicationJWT

## Request fields (application/json):

  - `discount` (object, required) — one of (discriminator: type):
    Coupon discount.
    - fixed:
      - `amount` (number, required)
        Amount of discount.
      - `currency` (string, required)
        Currency code in ISO 4217 format.
      - `type` (string, required)
        Enum: "fixed"
      - `context` (string)
        Context in which the discount applies.
        Enum: "items", "shipping", "items-and-shipping"
    - percent:
      - `value` (number, required)
        Percentage of discount.
      - `type` (string, required)
        Enum: "percent"
      - `context` (string)
        Context in which the discount applies.
        Enum: same as `context` in "fixed" (3 values)

  - `restrictions` (array) — one of (discriminator: type):
    Coupon restrictions.
All type values in this array must be unique.
    - discounts-per-redemption:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "discounts-per-redemption"
      - `quantity` (integer, required)
        Permitted number of discounts per redemption.
    - maximum-order-amount:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "maximum-order-amount"
      - `amount` (number, required)
        Maximum order amount that is allowed to apply the coupon.
      - `currency` (string, required)
        Currency code in ISO 4217 format.
    - minimum-order-amount:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "minimum-order-amount"
      - `amount` (number, required)
        Minimum order quantity that is required to apply the coupon.
      - `currency` (string, required)
        Currency code in ISO 4217 format.
    - paid-by-time:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "paid-by-time"
      - `time` (string, required)
        Date and time when a coupon redemption is no longer valid, and the coupon is removed from unpaid invoices if applied.

> Note: This date-time cannot be changed.
    - redemptions-per-customer:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "redemptions-per-customer"
      - `quantity` (integer, required)
        Permitted number of redemptions per customer.
    - restrict-to-bxgy:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-bxgy"
      - `buy` (array, required)
        One or more plan and quantity definitions that must be purchased to receive all plans and quantities that are defined in the get instruction.
All planId values in this array must be unique.
      - `buy.planId` (string, required)
        Plan ID of the item being purchased.
This value must be unique within the buy.items array.
        Example: "plan_0YV7DENSVGDBW9S71XZNNYYQ0X"
      - `buy.quantity` (integer, required)
        Total quantity of the associated plan ID that must be purchased for this restriction to apply.
      - `get` (array, required)
        One or more plan and quantity definitions that are added to a purchase if all definitions in the buy condition are met.
All planId values in this array must be unique.
      - `get.planId` (string, required)
        Plan ID of the item that is to be received by the customer.
This value must be unique within the get.items array.
        Example: "plan_0YV7DENSVGDBW9S71XZNNYYQ0X"
      - `get.quantity` (integer, required)
        Total quantity of the associated plan ID that is to be received by the customer.
    - restrict-to-countries:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-countries"
      - `countries` (array, required)
        Countries where the coupon can be applied, in ISO Alpha-2 code format.
For examples, see [ISO.org](https://www.iso.org/obp/ui/#search/code/).
    - restrict-to-customer-tags:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-customer-tags"
      - `tags` (array, required)
        Customer tags on which a coupon can be applied.
      - `requireAllTags` (boolean, required)
        Specifies if the customer must have all listed tags,
or at least one of the listed tags, to redeem a coupon.
        Enum: true, false
    - restrict-to-customers:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-customers"
      - `customerIds` (array, required)
        Customer IDs on which a coupon can be applied.
    - restrict-to-exclusive-application:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-exclusive-application"
    - restrict-to-invoices:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-invoices"
      - `invoiceIds` (array, required)
        Invoice IDs on which a coupon can be applied.
    - restrict-to-plans:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-plans"
      - `planIds` (array, required)
        Plan IDs on which a coupon can be applied.
      - `minimumQuantity` (integer)
        Minimum quantity that is required to apply the restriction and subsequent discount.
    - restrict-to-products:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-products"
      - `productIds` (array, required)
        Product IDs on which a coupon can be applied.
      - `minimumQuantity` (integer)
        Minimum quantity that is required to apply the restriction and subsequent discount.
    - restrict-to-subscriptions:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "restrict-to-subscriptions"
      - `subscriptionIds` (array, required)
        Subscription IDs on which a coupon can be applied.
    - total-redemptions:
      - `type` (string, required)
        Type of coupon restriction.
        Enum: "total-redemptions"
      - `quantity` (integer, required)
        Permitted total number of redemptions.

  - `description` (string)
    Description of the coupon.
Use this field to provide a description for the invoice discount item.

If this field is empty,
the invoice discount item description uses the related coupon ID,
in the following format: Coupon "COUPON-ID".

  - `issuedTime` (string, required)
    Date and time when the coupon is issued.
This value may also be described as start time of the coupon.

  - `expiredTime` (string,null)
    Date and time when the coupon expires.

## Response 401 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 422 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

  - `invalidFields` (array)
    Invalid field details.

  - `invalidFields.field` (string)
    Name of the field.
Dot notation is used for nested object field names.

  - `invalidFields.message` (string)
    Message field.

## Response 429 fields (application/json):

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".
    Example: "about:blank"

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
    Example: "Rate Limit Exceeded"

  - `status` (integer)
    HTTP status code.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.
    Example: "A request cannot be executed because the user has sent too many requests within a certain period of time"

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.