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

Authorizations:
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).

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID.

customerId
string <= 50 characters

Customer's ID.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

createdTime
string <date-time>

Coupon redeem time.

canceledTime
string <date-time>

Coupon redemption canceled time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

$couponRedemptions = $client->couponsRedemptions()->search([
    'filter' => 'customerId:testCustomer',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Redeem a coupon

Redeem a coupon.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Redeem a coupon.

couponId
string <= 50 characters

Coupon's ID.

customerId
string <= 50 characters

Customer's ID.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

The resource ID. Defaults to UUID v4.

couponId
string <= 50 characters

Coupon's ID.

customerId
string <= 50 characters

Customer's ID.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

createdTime
string <date-time>

Coupon redeem time.

canceledTime
string <date-time>

Coupon redemption canceled time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "additionalRestrictions": [
    ]
}

Response samples

Content type
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

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

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

The resource ID. Defaults to UUID v4.

couponId
string <= 50 characters

Coupon's ID.

customerId
string <= 50 characters

Customer's ID.

Array of objects (RedemptionRestriction)

Additional restrictions for coupon's redemptions.

createdTime
string <date-time>

Coupon redeem time.

canceledTime
string <date-time>

Coupon redemption canceled time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

$couponRedemption = $client->couponsRedemptions()->load('redemptionId');

Response samples

Content type
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

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Request samples

$client->couponsRedemptions()->cancel('id');

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Retrieve a list of coupons

Retrieve a list of coupons.

Authorizations:
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).

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID a.k.a redemption code.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string
Enum: "draft" "issued" "expired"

If coupon enabled.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Coupon created time.

updatedTime
string <date-time>

Coupon updated time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

$coupons = $client->coupons()->search([
    'filter' => 'status:issued',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Create a coupon

Create a coupon.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Coupon resource.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID a.k.a redemption code.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string
Enum: "draft" "issued" "expired"

If coupon enabled.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Coupon created time.

updatedTime
string <date-time>

Coupon updated time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "discount": {
    },
  • "restrictions": [
    ],
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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.

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID a.k.a redemption code.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string
Enum: "draft" "issued" "expired"

If coupon enabled.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Coupon created time.

updatedTime
string <date-time>

Coupon updated time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

$coupon = $client->coupons()->load('couponId');

Response samples

Content type
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.

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Coupon resource.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID a.k.a redemption code.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string
Enum: "draft" "issued" "expired"

If coupon enabled.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Coupon created time.

updatedTime
string <date-time>

Coupon updated time.

Array of objects (SelfLink) non-empty

The links related to resource.

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID a.k.a redemption code.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string
Enum: "draft" "issued" "expired"

If coupon enabled.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Coupon created time.

updatedTime
string <date-time>

Coupon updated time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "discount": {
    },
  • "restrictions": [
    ],
  • "description": "string",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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 expiry time with the specified coupon ID. The expiredTime of a coupon must be greater than its issuedTime. This cannot be performed on expired coupons.

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Coupon resource.

expiredTime
required
string <date-time>

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Coupon's ID a.k.a redemption code.

required
object (Discount)
Array of objects (CouponRestriction)

Coupon restrictions.

redemptionsCount
integer >= 0

Coupon's redemptions count.

status
string
Enum: "draft" "issued" "expired"

If coupon enabled.

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"'.

issuedTime
required
string <date-time>

Coupon's issued time (start time).

expiredTime
string <date-time>

Coupon's expire time (end time).

createdTime
string <date-time>

Coupon created time.

updatedTime
string <date-time>

Coupon updated time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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": [
    ]
}