# Upsert a coupon

Creates or updates (upserts) a coupon with a specified coupon ID.

Endpoint: PUT /coupons/{id}
Version: latest
Security: SecretApiKey, JWT, ApplicationJWT

## Path parameters

- `id` (string, required)
  ID of the resource.

## Request fields

- `discount` (object, required)
  Coupon discount.
- `restrictions` (array)
  Coupon restrictions. All `type` values in this array must be unique.
- `restrictions.type` (string, required)
  Type of coupon restriction.
  Enum: "total-redemptions"
- `restrictions.quantity` (integer, required)
  Permitted number of discounts per redemption.
- `restrictions.amount` (number, required)
  Maximum order amount that is allowed to apply the coupon.
- `restrictions.currency` (string, required)
  Currency code in ISO 4217 format.
  Example: USD
- `restrictions.amount` (number, required)
  Minimum order quantity that is required to apply the coupon.
- `restrictions.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.
- `restrictions.quantity` (integer, required)
  Permitted number of redemptions per customer.
- `restrictions.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.
- `restrictions.buy.planId` (string, required)
  Plan ID of the item being purchased. This value must be unique within the `buy.items` array.
  Example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X
- `restrictions.buy.quantity` (integer, required)
  Total quantity of the associated plan ID that must be purchased for this restriction to apply.
- `restrictions.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.
- `restrictions.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
- `restrictions.get.quantity` (integer, required)
  Total quantity of the associated plan ID that is to be received by the customer.
- `restrictions.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/).
- `restrictions.tags` (array, required)
  Customer tags on which a coupon can be applied.
- `restrictions.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
- `restrictions.customerIds` (array, required)
  Customer IDs on which a coupon can be applied.
- `restrictions.invoiceIds` (array, required)
  Invoice IDs on which a coupon can be applied.
- `restrictions.planIds` (array, required)
  Plan IDs on which a coupon can be applied.
- `restrictions.minimumQuantity` (integer)
  Minimum quantity that is required to apply the restriction and subsequent discount.
- `restrictions.productIds` (array, required)
  Product IDs on which a coupon can be applied.
- `restrictions.subscriptionIds` (array, required)
  Subscription IDs on which a coupon can be applied.
- `restrictions.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 200 fields

- `id` (string)
  ID of the coupon. This value is also known as the coupon redemption code.
  Example: cpn_0YVCNKF81GD778N4YNVGDJK558
- `discount` (object, required)
  Coupon discount.
- `restrictions` (array)
  Coupon restrictions. All `type` values in this array must be unique.
- `restrictions.type` (string, required)
  Type of coupon restriction.
  Enum: "total-redemptions"
- `restrictions.quantity` (integer, required)
  Permitted number of discounts per redemption.
- `restrictions.amount` (number, required)
  Maximum order amount that is allowed to apply the coupon.
- `restrictions.currency` (string, required)
  Currency code in ISO 4217 format.
  Example: USD
- `restrictions.amount` (number, required)
  Minimum order quantity that is required to apply the coupon.
- `restrictions.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.
- `restrictions.quantity` (integer, required)
  Permitted number of redemptions per customer.
- `restrictions.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.
- `restrictions.buy.planId` (string, required)
  Plan ID of the item being purchased. This value must be unique within the `buy.items` array.
  Example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X
- `restrictions.buy.quantity` (integer, required)
  Total quantity of the associated plan ID that must be purchased for this restriction to apply.
- `restrictions.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.
- `restrictions.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
- `restrictions.get.quantity` (integer, required)
  Total quantity of the associated plan ID that is to be received by the customer.
- `restrictions.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/).
- `restrictions.tags` (array, required)
  Customer tags on which a coupon can be applied.
- `restrictions.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
- `restrictions.customerIds` (array, required)
  Customer IDs on which a coupon can be applied.
- `restrictions.invoiceIds` (array, required)
  Invoice IDs on which a coupon can be applied.
- `restrictions.planIds` (array, required)
  Plan IDs on which a coupon can be applied.
- `restrictions.minimumQuantity` (integer)
  Minimum quantity that is required to apply the restriction and subsequent discount.
- `restrictions.productIds` (array, required)
  Product IDs on which a coupon can be applied.
- `restrictions.subscriptionIds` (array, required)
  Subscription IDs on which a coupon can be applied.
- `restrictions.quantity` (integer, required)
  Permitted total number of redemptions.
- `redemptionsCount` (integer)
  Total number of times that a coupon is redeemed.
- `status` (string)
  Specifies the current status of the coupon.
  Enum: "draft", "issued", "expired"
- `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.
- `revision` (integer)
  Number of times the coupon data has been modified. Use the revision number when analyzing webhook data to determine if a change should take precedence over the current representation.
- `createdTime` (string)
  Date and time when the resource is created. This value is set automatically when the resource is created.
- `updatedTime` (string)
  Date and time when the resource is updated. This value is set automatically when the resource is updated.
- `_links` (array)
  Related links.
- `_links.href` (string)
  Link URL.
- `_links.rel` (string)
  Type of link.
  Enum: "self"

## Response 201 fields

- `id` (string)
  ID of the coupon. This value is also known as the coupon redemption code.
  Example: cpn_0YVCNKF81GD778N4YNVGDJK558
- `discount` (object, required)
  Coupon discount.
- `restrictions` (array)
  Coupon restrictions. All `type` values in this array must be unique.
- `restrictions.type` (string, required)
  Type of coupon restriction.
  Enum: "total-redemptions"
- `restrictions.quantity` (integer, required)
  Permitted number of discounts per redemption.
- `restrictions.amount` (number, required)
  Maximum order amount that is allowed to apply the coupon.
- `restrictions.currency` (string, required)
  Currency code in ISO 4217 format.
  Example: USD
- `restrictions.amount` (number, required)
  Minimum order quantity that is required to apply the coupon.
- `restrictions.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.
- `restrictions.quantity` (integer, required)
  Permitted number of redemptions per customer.
- `restrictions.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.
- `restrictions.buy.planId` (string, required)
  Plan ID of the item being purchased. This value must be unique within the `buy.items` array.
  Example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X
- `restrictions.buy.quantity` (integer, required)
  Total quantity of the associated plan ID that must be purchased for this restriction to apply.
- `restrictions.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.
- `restrictions.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
- `restrictions.get.quantity` (integer, required)
  Total quantity of the associated plan ID that is to be received by the customer.
- `restrictions.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/).
- `restrictions.tags` (array, required)
  Customer tags on which a coupon can be applied.
- `restrictions.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
- `restrictions.customerIds` (array, required)
  Customer IDs on which a coupon can be applied.
- `restrictions.invoiceIds` (array, required)
  Invoice IDs on which a coupon can be applied.
- `restrictions.planIds` (array, required)
  Plan IDs on which a coupon can be applied.
- `restrictions.minimumQuantity` (integer)
  Minimum quantity that is required to apply the restriction and subsequent discount.
- `restrictions.productIds` (array, required)
  Product IDs on which a coupon can be applied.
- `restrictions.subscriptionIds` (array, required)
  Subscription IDs on which a coupon can be applied.
- `restrictions.quantity` (integer, required)
  Permitted total number of redemptions.
- `redemptionsCount` (integer)
  Total number of times that a coupon is redeemed.
- `status` (string)
  Specifies the current status of the coupon.
  Enum: "draft", "issued", "expired"
- `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.
- `revision` (integer)
  Number of times the coupon data has been modified. Use the revision number when analyzing webhook data to determine if a change should take precedence over the current representation.
- `createdTime` (string)
  Date and time when the resource is created. This value is set automatically when the resource is created.
- `updatedTime` (string)
  Date and time when the resource is updated. This value is set automatically when the resource is updated.
- `_links` (array)
  Related links.
- `_links.href` (string)
  Link URL.
- `_links.rel` (string)
  Type of link.
  Enum: "self"

## Response 401 fields

- `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 404 fields

- `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 409 fields

- `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

- `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.
  Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]
- `invalidFields.field` (string)
  Name of the field. Dot notation is used for nested object field names.
- `invalidFields.message` (string)
  Message field.

## Response 429 fields

- `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.
