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. discounts-per-redemption
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

200
401
403

application/json

[{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
],
"createdTime": "2019-08-24T14:15:22Z",
"canceledTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}
]

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. discounts-per-redemption
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. discounts-per-redemption
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": [{"type": "discounts-per-redemption"
}
]
}

Response samples

201
401
403
422

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
],
"createdTime": "2019-08-24T14:15:22Z",
"canceledTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

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. discounts-per-redemption
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

200
401
403
404

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"couponId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"additionalRestrictions": [{"type": "discounts-per-redemption"
}
],
"createdTime": "2019-08-24T14:15:22Z",
"canceledTime": "2019-08-24T14:15:22Z",
"_links": [{"rel": "self",
"href": "string"
}
]
}

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

401
403
404

application/json

{"status": 401,
"type": "http://example.com",
"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. discounts-per-redemption
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

200
401
403

application/json

[{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"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": [{"rel": "self",
"href": "string"
}
]
}
]

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. discounts-per-redemption
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. discounts-per-redemption
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": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"description": "string",
"issuedTime": "2019-08-24T14:15:22Z",
"expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

201
401
403
422

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"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": [{"rel": "self",
"href": "string"
}
]
}

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. discounts-per-redemption
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

200
401
403
404

application/json

{"id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
"discount": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"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": [{"rel": "self",
"href": "string"
}
]
}

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. discounts-per-redemption
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. discounts-per-redemption
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. discounts-per-redemption
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": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"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": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"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": [{"rel": "self",
"href": "string"
}
]
}

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. discounts-per-redemption
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": {"type": "fixed",
"context": "items"
},
"restrictions": [{"type": "discounts-per-redemption"
}
],
"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": [{"rel": "self",
"href": "string"
}
]
}