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
[
  • {
    },
  • {
    },
  • {
    }
]
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 (categoryRestricted) 
 Default:  false
Defines if the coupon has category restrictions.




Info: Cannot be combined together with the segment restrictions.


 
segmentRestricted
boolean (segmentRestricted) 
 Default:  false
Defines if the coupon has segment restrictions. If the value is set to true, the restrictions.segments must be provided.




Info: Cannot be combined neither with the category restrictions nor with customers 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,
  • "segmentRestricted": false,
  • "restrictions": {
    },
  • "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,
  • "segmentRestricted": 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.


 
discountCalculationType
string
 Default:  "SUBTOTAL"
Determines whether the coupon is applied to the total or subtotal value of the order.


 Enum: "TOTAL" "SUBTOTAL"  
categoryRestricted
boolean (categoryRestricted) 
 Default:  false
Defines if the coupon has category restrictions.




Info: Cannot be combined together with the segment restrictions.


 
segmentRestricted
boolean (segmentRestricted) 
 Default:  false
Defines if the coupon has segment restrictions. If the value is set to true, the restrictions.segments must be provided.




Info: Cannot be combined neither with the category restrictions nor with customers 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,
  • "segmentRestricted": 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.


 
discountCalculationType
string
 Default:  "SUBTOTAL"
Determines whether the coupon is applied to the total or subtotal value of the order.


 Enum: "TOTAL" "SUBTOTAL"  
categoryRestricted
boolean (categoryRestricted) 
 Default:  false
Defines if the coupon has category restrictions.




Info: Cannot be combined together with the segment restrictions.


 
segmentRestricted
boolean (segmentRestricted) 
 Default:  false
Defines if the coupon has segment restrictions. If the value is set to true, the restrictions.segments must be provided.




Info: Cannot be combined neither with the category restrictions nor with customers 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,
  • "segmentRestricted": 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.


 
legalEntityId
string
The id of the legal entity to which customer is assigned. When customer is assigned to many legal entities then he can redeem the same coupon separately for each legal entity.


 
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.


 
legalEntityId
string
The id of the legal entity to which customer is assigned. When customer is assigned to many legal entities then he can redeem the same coupon separately for each legal entity.


 
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
{
  • "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": {
    },
  • "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": [
    ]
}