Coupons

Coupons allows to apply different types of discounts to Invoices, Orders and Plans. Redeemed Coupons will be applied only to Invoices with the same currency.

Retrieve a list of coupon redemptions

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

Coupons redemptions were retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

couponId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

canceledTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/coupons-redemptions
Request samples
$couponRedemptions = $client->couponsRedemptions()->search([
    'filter' => 'customerId:testCustomer',
]);
Response samples
application/json
[
  • {
    }
]

Redeem a coupon

Redeem a coupon.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Redeem a coupon.

couponId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

Responses
201

Coupon was redeemed.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

couponId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

canceledTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/coupons-redemptions
Request samples
application/json
{
  • "couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "additionalRestrictions": [
    ]
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "additionalRestrictions": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "canceledTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a coupon redemption with specified identifier string

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

Retrieve a coupon redemption with specified identifier string.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

couponId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

canceledTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/coupons-redemptions/{id}
Request samples
$couponRedemption = $client->couponsRedemptions()->load('redemptionId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "additionalRestrictions": [
    ],
  • "createdTime": "2019-08-24T14:15:22Z",
  • "canceledTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Cancel a coupon redemption

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
201

Cancel a coupon redemption.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

post/coupons-redemptions/{id}/cancel
Request samples
$client->couponsRedemptions()->cancel('id');
Response samples
application/json
{
  • "status": 401,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Retrieve a list of coupons

Retrieve a list of coupons.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

A list of coupons was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string

If coupon enabled.

Enum: "draft" "issued" "expired"
description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/coupons
Request samples
$coupons = $client->coupons()->search([
    'filter' => 'status:issued',
]);
Response samples
application/json
[
  • {
    }
]

Create a coupon

Create a coupon.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Coupon resource.

required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

Responses
201

Coupon was created.

Response Schema: application/json
required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string

If coupon enabled.

Enum: "draft" "issued" "expired"
description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/coupons
Request samples
application/json
{
  • "discount": {
    },
  • "restrictions": [
    ],
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "discount": {
    },
  • "restrictions": [
    ],
  • "redemptionsCount": 0,
  • "status": "draft",
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a coupon

Retrieve a coupon with specified coupon ID string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

Coupon was retrieved successfully.

Response Schema: application/json
required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string

If coupon enabled.

Enum: "draft" "issued" "expired"
description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/coupons/{id}
Request samples
$coupon = $client->coupons()->load('couponId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "discount": {
    },
  • "restrictions": [
    ],
  • "redemptionsCount": 0,
  • "status": "draft",
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Create or update a coupon with predefined coupon ID

Create or update a coupon with predefined coupon ID.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Coupon resource.

required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

Responses
200

Coupon was updated.

Response Schema: application/json
required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string

If coupon enabled.

Enum: "draft" "issued" "expired"
description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

201

Coupon was created.

Response Schema: application/json
required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string

If coupon enabled.

Enum: "draft" "issued" "expired"
description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

404

Resource was not found.

409

Conflict.

422

Invalid data was sent.

put/coupons/{id}
Request samples
application/json
{
  • "discount": {
    },
  • "restrictions": [
    ],
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "discount": {
    },
  • "restrictions": [
    ],
  • "redemptionsCount": 0,
  • "status": "draft",
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Set a coupon's expiration time

Set a coupon's expiration time with the specified coupon ID. The expiredTime of a coupon must be greater than its issuedTime. This cannot be performed on expired coupons.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Coupon resource.

expiredTime
required
string <date-time>

The coupon's expiration time, must be greater than the issued time. Null or empty string will immediately expire the coupon.

Responses
201

Coupon expiration was successfully set.

Response Schema: application/json
required
object (Discount)
amount
required
number <double> > 0

Discount amount.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

type
string

Discount type.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

issuedTime
required
string <date-time>

Coupon's issued time (start time).

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (CouponRestriction)

Coupon restrictions.

Array
type
required
string

Redemption's additional restriction type.

quantity
required
integer

Restriction quantity.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string

If coupon enabled.

Enum: "draft" "issued" "expired"
description
string

Your coupon description. When it is not empty this is used for invoice discount item description, otherwise the item's description uses coupon's ID like 'Coupon "COUPON-ID"'.

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

409

The coupon is already expired and has been redeemed, unable to. reschedule expiration.

422

Invalid data was sent.

post/coupons/{id}/expiration
Request samples
application/json
{
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "discount": {
    },
  • "restrictions": [
    ],
  • "redemptionsCount": 0,
  • "status": "draft",
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}