Coupon Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

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
coupon.coupon_read

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

[{"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": {"version": 1
},
"code": "MW2023_7",
"status": "EXPIRED",
"maxRedemptions": -1,
"redemptionCount": 0,
"deleted": false,
"restrictions": {"validFrom": "2023-02-09T06:45:33.779Z",
"validUntil": "2023-07-31T05:45:25.934Z",
"minOrderValue": {"amount": 150,
"currency": "EUR"
},
"validFor": [ ]
}
},
{"name": "MW2023_10",
"description": "BUY MORE SAVE MORE! 10% off orders over 500€! Use code: MW2023_10",
"discountType": "PERCENT",
"discountPercentage": 10,
"allowAnonymous": false,
"maxRedemptionsPerCustomer": -1,
"categoryRestricted": false,
"metadata": {"version": 3
},
"code": "MW2023_10",
"status": "VALID",
"maxRedemptions": -1,
"redemptionCount": 0,
"deleted": false,
"restrictions": {"validFrom": "2023-02-09T06:47:29.177Z",
"minOrderValue": {"amount": 500,
"currency": "EUR"
},
"validFor": [ ]
}
}
]

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.
discountCalculationType	string Default: "SUBTOTAL" Determines whether the coupon is applied to the total or subtotal value of the order. Enum: "TOTAL" "SUBTOTAL"
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": {"amount": 24.99,
"currency": "USD"
},
"allowAnonymous": false,
"maxRedemptions": -1,
"maxRedemptionsPerCustomer": -1,
"categoryRestricted": false,
"restrictions": {"validFor": ["C0123456789",
"C0123456788"
],
"validFrom": "2014-12-01T00:00:00.000Z",
"validUntil": "2015-01-31T23:59:59.999Z",
"minOrderValue": {"amount": 49.99,
"currency": "USD"
}
},
"issuedTo": "C01234567989"
}

Response samples

application/json

{"id": "ENG2OC0"
}

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": {"version": 1
},
"code": "MW2023_7",
"status": "EXPIRED",
"maxRedemptions": -1,
"redemptionCount": 0,
"deleted": false,
"restrictions": {"validFrom": "2023-02-09T06:45:33.779Z",
"validUntil": "2023-07-31T05:45:25.934Z",
"minOrderValue": {"amount": 150,
"currency": "EUR"
},
"validFor": [ ]
}
}

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.
discountCalculationType	string Default: "SUBTOTAL" Determines whether the coupon is applied to the total or subtotal value of the order. Enum: "TOTAL" "SUBTOTAL"
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": {"version": 4
},
"maxRedemptions": -1,
"restrictions": {"validFrom": "2023-02-09T06:45:33.779Z",
"validUntil": "2023-07-31T05:45:25.934Z",
"minOrderValue": {"amount": 150,
"currency": "EUR"
},
"validFor": [ ]
}
}

Response samples

application/json

{"type": "validation_violation",
"status": 400,
"message": "The request violates validation constraints.",
"details": [{"type": "missing_payload",
"message": "Empty payload was sent",
"moreInfo": ""
}
]
}

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.
discountCalculationType	string Default: "SUBTOTAL" Determines whether the coupon is applied to the total or subtotal value of the order. Enum: "TOTAL" "SUBTOTAL"
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": {"version": 4
},
"maxRedemptions": -1,
"restrictions": {"validFrom": "2023-02-09T06:45:33.779Z",
"validUntil": "2023-07-31T05:45:25.934Z",
"minOrderValue": {"amount": 150,
"currency": "EUR"
},
"validFor": [ ]
}
}

Response samples

application/json

{"type": "validation_violation",
"status": 400,
"message": "The request violates validation constraints.",
"details": [{"type": "missing_payload",
"message": "Empty payload was sent",
"moreInfo": ""
}
]
}

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": [{"type": "missing_payload",
"message": "Empty payload was sent",
"moreInfo": ""
}
]
}

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": {"amount": 1090,
"currency": "EUR"
},
"discount": {"amount": 5,
"currency": "EUR"
}
}

Response samples

application/json

{"type": "validation_violation",
"status": 400,
"message": "The request violates validation constraints.",
"details": [{"type": "missing_payload",
"message": "Empty payload was sent",
"moreInfo": ""
}
]
}

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

[{"id": "6429b8fdf8fd8e0001df1617",
"code": "10-OFF",
"customerNumber": "61443563",
"orderTotal": {"amount": 299.3,
"currency": "USD"
},
"discount": {"amount": 29.93,
"currency": "USD"
},
"redeemedAt": "2023-04-02T17:18:53.701Z"
},
{"id": "642aa7f5f8fd8e0001df161b",
"code": "10-OFF",
"customerNumber": "61443563",
"orderTotal": {"amount": 369.07,
"currency": "USD"
},
"discount": {"amount": 36.91,
"currency": "USD"
},
"redeemedAt": "2023-04-03T10:18:29.233Z"
}
]

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": {"amount": 1090,
"currency": "EUR"
},
"discount": {"amount": 5,
"currency": "EUR"
}
}

Response samples

application/json

{"id": "6058912da917ae6f360f2557"
}

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": {"amount": 299.3,
"currency": "USD"
},
"discount": {"amount": 29.93,
"currency": "USD"
},
"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": [{"type": "missing_payload",
"message": "Empty payload was sent",
"moreInfo": ""
}
]
}