Coupon Service

Download OpenAPI specification:Download

Generate secure and highly performant promotional coupons.


Key Features:

  • Absolute (value) based coupons in a particular currency (such as £10 off)
  • Relative (percentage) based coupons (such as 10% off)
  • Free shipping coupon
  • Restrict coupons to be redeemed against specific product categories
  • Restrict the number of times a coupon can be redeemed by one user or in total all together
  • Restrict by date (from / to)
  • Define a minimum order value required before the coupon can be redeemed
  • Built for high-throughput and scale

Key Benefits:

  • Run promotion campaigns
  • Use in marketing material to drive traffic to your website
  • Increase customer loyalty
  • Drive sales for last season's stock or overstock items

Coupon Management

Retrieving list of coupons by criteria

Retrieves a list of coupons by the specified criteria. Supports sorting and paging.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

query Parameters
sort
string

The list of comma-separated properties used to sort the results. By default, the column values are sorted in ascending order. Can either be in the form of fieldName or fieldName:asc,fieldName:desc. If you want to sort by localized attributes, you must use the following form: fieldName.language or fieldName.language:asc,fieldName.language:desc.

pageNumber
integer >= 1
Default: 1

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

pageSize
integer >= 1
Default: 16

The number of documents being retrieved on the page.

totalCount
boolean

This parameter requests to return the total number of object in the collection fulfilling the criteria together with the response. This number will be returned in the 'items-count' header.

q
string

The simple query criteria based on available fields to limit returned results or a set of modified documents.

showDeleted
boolean
Default: false

Includes deleted coupons in the result.

Responses
200

The list of coupons has been retrieved successfully.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

500

Some server side error occurred.

get/{tenant}/coupons
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Creating a new coupon

Creates a coupon.

By default, the coupon code is saved in uppercase. To ensure that the code is saved both in upper and lower case, set the enableCouponCodeCaseSensitivity configuration to true in the configuration service or System Preferences.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Request Body schema: application/json
code
string

e.g.: WINTER-SALE, 10OFF. If not provided, a code will be auto generated.

name
required
string

Coupon name.

description
string

Coupon description.

discountType
string
Default: "ABSOLUTE"

'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.

Enum: "PERCENT" "ABSOLUTE" "FREE_SHIPPING"
discountPercentage
number [ 0 .. 100 ]

A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.

object (Money amount)

Defines an amount in a specific currency.

allowAnonymous
boolean
Default: false

Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.

maxRedemptions
number
Default: -1

Maximum number of redemptions; -1 designates 'unlimited' (seller-only).

maxRedemptionsPerCustomer
number
Default: -1

Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

categoryRestricted
boolean
Default: false

Defines if the coupon has category restrictions.

object (restrictions)

Restrictions of the coupon.

issuedTo
string

The Id of the customer who originally received the coupon (seller-only).

mixins
object

The field contains mixins values.

object
Responses
201

The resource has been successfully created.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/coupons
Request samples
application/json
{
  • "code": "ENG2OC0",
  • "name": "Winter Sale 2018",
  • "description": "Great Winter Discount of 25 USD in December 2018 and January 2019 for all Orders over 50 USD",
  • "discountType": "ABSOLUTE",
  • "discountAbsolute": {
    },
  • "allowAnonymous": false,
  • "maxRedemptions": -1,
  • "maxRedemptionsPerCustomer": -1,
  • "categoryRestricted": false,
  • "restrictions": {
    },
  • "issuedTo": "C01234567989"
}
Response samples
application/json

Retrieving information about particular coupon by code

Retrieves coupon details.


Required scopes

  • coupon.coupon_redeem_on_behalf - needed only if the service should use the customer identification specified in the request query (customerNumber attribute) instead of the one associated with current authentication token.
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

query Parameters
customerNumber
string

Customer number (ID) of customer on behalf of which we request coupon information. Needed only in case of retrieving coupon eligible for other customer than the caller.

Responses
200

The coupon has been successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/coupons/{code}
Request samples
Response samples
application/json
{
  • "name": "MW2023_7",
  • "description": "BUY MORE SAVE MORE! 7% off orders over 150€! Use code: MW2023_7",
  • "discountType": "PERCENT",
  • "discountPercentage": 7,
  • "allowAnonymous": false,
  • "maxRedemptionsPerCustomer": -1,
  • "categoryRestricted": false,
  • "metadata": {
    },
  • "code": "MW2023_7",
  • "status": "EXPIRED",
  • "maxRedemptions": -1,
  • "redemptionCount": 0,
  • "deleted": false,
  • "restrictions": {
    }
}

Updating the coupon by code

Updates an existing coupon.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

query Parameters
partial
required
boolean

If true, a partial update will be supported, otherwise the full object replacement will be performed.

This parameter is DEPRECATED. For partial updates, please use PATCH method instead.

Request Body schema: application/json
name
string

Coupon name.

description
string

Coupon description.

discountType
string

'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.

Enum: "PERCENT" "ABSOLUTE" "FREE_SHIPPING"
discountPercentage
number [ 0 .. 100 ]

A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.

object

Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.

allowAnonymous
boolean
Default: false

Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.

maxRedemptions
number
Default: -1

Maximum number of redemptions; -1 designates 'unlimited' (seller-only).

maxRedemptionsPerCustomer
number
Default: -1

Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

categoryRestricted
boolean
Default: false

Defines if the coupon has category restrictions.

object (restrictions)

Restrictions of the coupon.

issuedTo
string

The Id of the customer who originally received the coupon (seller-only).

mixins
object

The field contains mixins values.

object
Responses
200

The coupon has been successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

put/{tenant}/coupons/{code}
Request samples
application/json
{
  • "name": "MW2023_7",
  • "description": "BUY MORE SAVE MORE! 7% off orders over 150€! Use code: MW2023_7",
  • "discountType": "PERCENT",
  • "discountPercentage": 7,
  • "allowAnonymous": false,
  • "maxRedemptionsPerCustomer": -1,
  • "categoryRestricted": false,
  • "metadata": {
    },
  • "maxRedemptions": -1,
  • "restrictions": {
    }
}
Response samples
application/json
{
  • "type": "validation_violation",
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "details": [
    ]
}

Partially updating the coupon by code

Partially updates an existing coupon.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Request Body schema: application/json
name
string

Coupon name.

description
string

Coupon description.

discountType
string

'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.

Enum: "PERCENT" "ABSOLUTE" "FREE_SHIPPING"
discountPercentage
number [ 0 .. 100 ]

A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.

object

Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.

allowAnonymous
boolean
Default: false

Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.

maxRedemptions
number
Default: -1

Maximum number of redemptions; -1 designates 'unlimited' (seller-only).

maxRedemptionsPerCustomer
number
Default: -1

Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

categoryRestricted
boolean
Default: false

Defines if the coupon has category restrictions.

object (restrictions)

Restrictions of the coupon.

issuedTo
string

The Id of the customer who originally received the coupon (seller-only).

mixins
object

The field contains mixins values.

object
Responses
200

The coupon has been successfully updated.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

patch/{tenant}/coupons/{code}
Request samples
application/json
{
  • "name": "MW2023_7",
  • "description": "BUY MORE SAVE MORE! 7% off orders over 150€! Use code: MW2023_7",
  • "discountType": "PERCENT",
  • "discountPercentage": 7,
  • "allowAnonymous": false,
  • "maxRedemptionsPerCustomer": -1,
  • "categoryRestricted": false,
  • "metadata": {
    },
  • "maxRedemptions": -1,
  • "restrictions": {
    }
}
Response samples
application/json
{
  • "type": "validation_violation",
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "details": [
    ]
}

Deleting a coupon by code

Deletes an existing coupon.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Responses
204

Coupon with given code has been successfully deleted.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

500

Some server side error occurred.

delete/{tenant}/coupons/{code}
Request samples
Response samples
application/json
{
  • "type": "validation_violation",
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "details": [
    ]
}

Coupon Validation

Validating redeemability of a coupon

Checks whether the coupon can be successfully redeemed. Performs all checks that are executed during actual redemption, but does not result in a redeemed coupon. Only the status of the validation is reported.


Required scopes

  • coupon.coupon_redeem_on_behalf - needed only if the service should use the customer identification specified in the request body (customerNumber attribute) instead of the one associated with current authentication token.
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Request Body schema: application/json
orderCode
string

Code of the associated order.

customerNumber
string

The customer Id of the user, e.g. C0123456789. Can be specified only if coupon.coupon_redeem_on_behalf scope is present.

required
object (Money amount)

Defines an amount in a specific currency.

required
object (Money amount)

Defines an amount in a specific currency.

Responses
200

The coupon can be successfully redeemed.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

500

Some server side error occurred.

post/{tenant}/coupons/{code}/validation
Request samples
application/json
{
  • "customerNumber": "CustomerId",
  • "orderTotal": {
    },
  • "discount": {
    }
}
Response samples
application/json
{
  • "type": "validation_violation",
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "details": [
    ]
}

Coupon Redemption

Retrieving a list of redemptions by criteria

Retrieves a list of redemptions by the specified criteria. Supports sorting and paging.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

query Parameters
sort
string

The list of comma-separated properties used to sort the results. By default, the column values are sorted in ascending order. Can either be in the form of fieldName or fieldName:asc,fieldName:desc. If you want to sort by localized attributes, you must use the following form: fieldName.language or fieldName.language:asc,fieldName.language:desc.

pageNumber
integer >= 1
Default: 1

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

pageSize
integer >= 1
Default: 16

The number of documents being retrieved on the page.

totalCount
boolean

This parameter requests to return the total number of object in the collection fulfilling the criteria together with the response. This number will be returned in the 'items-count' header.

q
string

The simple query criteria based on available fields to limit returned results or a set of modified documents.

Responses
200

List of redemptions

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/coupons/{code}/redemptions
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Redeeming the coupon by creating a redemption

Invalidate the coupon based on its validity scope. Redemption is not possible when the coupon has exceeded its maximum number allowed redemptions. To be redeemed a coupon needs to be already valid and not expired yet.


Required scopes

  • coupon.coupon_redeem_on_behalf - needed only if the service should use the customer identification specified in the request body (customerNumber attribute) instead of the one associated with current authentication token.
SecurityOAuth2
Request
path Parameters
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Request Body schema: application/json
orderCode
string

Code of the associated order.

customerNumber
string

The customer Id of the user, e.g. C0123456789. Can be specified only if coupon.coupon_redeem_on_behalf scope is present.

required
object (Money amount)

Defines an amount in a specific currency.

required
object (Money amount)

Defines an amount in a specific currency.

Responses
201

The coupon has been redeemed and the redemption has been successfully created.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

409

Creation failed because there was a conflict with another resource. Any details will be provided within the response payload.

500

Some server side error occurred.

post/{tenant}/coupons/{code}/redemptions
Request samples
application/json
{
  • "customerNumber": "CustomerId",
  • "orderTotal": {
    },
  • "discount": {
    }
}
Response samples
application/json

Retrieving a coupon redemption

Retrieves a single redemption.


Required scopes

  • coupon.coupon_manage for accessing any redemption.
  • coupon.coupon_redeem for accessing only redemption created by current user.
  • coupon.coupon_redeem_on_behalf - needed only if the service should use the customer identification specified in the request body (customerNumberattribute) instead of the one associated with current authentication token.
SecurityOAuth2
Request
path Parameters
id
required
string
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

query Parameters
customerNumber
string

Customer number (ID) of customer on behalf of which we request coupon information. Needed only in case of retrieving coupon eligible for other customer than the caller.

Responses
200

The coupon redemption has been successfully retrieved.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

500

Some server side error occurred.

get/{tenant}/coupons/{code}/redemptions/{id}
Request samples
Response samples
application/json
{
  • "id": "6429b8fdf8fd8e0001df1617",
  • "code": "10-OFF",
  • "customerNumber": "61443563",
  • "orderTotal": {
    },
  • "discount": {
    },
  • "redeemedAt": "2023-04-02T17:18:53.701Z"
}

Deleting a coupon redemption

Deletes a previously created redemption.


Required scopes

  • coupon.coupon_manage
SecurityOAuth2
Request
path Parameters
id
required
string
code
required
string

Code of a coupon

tenant
required
string [ 3 .. 16 ] characters

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Responses
204

A redemption with the provided code has been successfully deleted.

400

Request syntactically incorrect. Any details will be provided within the response payload.

401

Example response

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

500

Some server side error occurred.

delete/{tenant}/coupons/{code}/redemptions/{id}
Request samples
Response samples
application/json
{
  • "type": "validation_violation",
  • "status": 400,
  • "message": "The request violates validation constraints.",
  • "details": [
    ]
}