Community Support Portal YouTube Start a free trial

Coupon Management

PreviousAPI Reference NextCoupon Validation

Was this helpful?

Retrieving list of coupons by criteria

get

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

The endpoint was previously available under the /coupon-v2/ base path.

Required scopes

coupon.coupon_manage
coupon.coupon_read

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Query parameters

sortstringOptional

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.

pageNumberinteger · min: 1Optional

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.

Default: 1

pageSizeinteger · min: 1Optional

The number of documents being retrieved on the page.

Default: 16

totalCountbooleanOptional

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.

qstringOptional

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

showDeletedbooleanOptional

Includes deleted coupons in the result.

Default: false

Responses

200

The list of coupons has been retrieved successfully.

application/json

400

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

application/json

401

Example response

application/json

403

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

application/json

500

Some server side error occurred.

application/json

get

GET /coupon/{tenant}/coupons HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Creating a new coupon

post

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.

The endpoint was previously available under the /coupon-v2/ base path.

Required scopes

coupon.coupon_manage

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Body

Coupon creation schema.

codestringOptional

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

namestringRequired

Coupon name.

descriptionstringOptional

Coupon description.

discountTypestring · enumOptional

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

Default: ABSOLUTEPossible values:

discountPercentagenumber · max: 100Optional

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

discountAbsoluteall ofOptional

and

anyOptional

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

allowAnonymousbooleanOptional

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

Default: false

maxRedemptionsnumberOptional

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

Default: -1

maxRedemptionsPerCustomernumberOptional

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

Default: -1

discountCalculationTypestring · enumOptional

Determines whether the coupon is applied to the total or subtotal value of the order.

Default: SUBTOTALPossible values:

categoryRestrictedbooleanOptional

Defines if the coupon has category restrictions.

Info: Cannot be combined together with the segment restrictions.

Default: false

segmentRestrictedbooleanOptional

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.

Default: false

issuedTostringOptional

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

Responses

201

The resource has been successfully created.

application/json

400

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

application/json

401

Example response

application/json

403

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

application/json

409

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

application/json

500

Some server side error occurred.

application/json

post

POST /coupon/{tenant}/coupons HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 572

{
  "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,
  "segmentRestricted": 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"
}

{
  "id": "ENG2OC0"
}

Retrieving information about particular coupon by code

get

Retrieves coupon details.

The endpoint was previously available under the /coupon-v2/ base path.

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.

Authorizations

Path parameters

codestringRequired

Code of a coupon

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Query parameters

customerNumberstringOptional

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.

application/json

Responseall of

400

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

application/json

401

Example response

application/json

404

The requested resource does not exist.

application/json

500

Some server side error occurred.

application/json

get

GET /coupon/{tenant}/coupons/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Deleting a coupon by code

delete

Deletes an existing coupon.

The endpoint was previously available under the /coupon-v2/ base path.

Required scopes

coupon.coupon_manage

Authorizations

Path parameters

codestringRequired

Code of a coupon

tenantstring · min: 3 · max: 16Required

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.

application/json

401

Example response

application/json

403

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

application/json

404

The requested resource does not exist.

application/json

500

Some server side error occurred.

application/json

delete

DELETE /coupon/{tenant}/coupons/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Updating the coupon by code

put

Updates an existing coupon.

The endpoint was previously available under the /coupon-v2/ base path.

Required scopes

coupon.coupon_manage

Authorizations

Path parameters

codestringRequired

Code of a coupon

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Query parameters

partialbooleanRequired

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.

Body

Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.

namestringOptional

Coupon name.

descriptionstringOptional

Coupon description.

discountTypestring · enumOptional

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

Possible values:

discountPercentagenumber · max: 100Optional

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

allowAnonymousbooleanOptional

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

Default: false

maxRedemptionsnumberOptional

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

Default: -1

maxRedemptionsPerCustomernumberOptional

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

Default: -1

discountCalculationTypestring · enumOptional

Determines whether the coupon is applied to the total or subtotal value of the order.

Default: SUBTOTALPossible values:

categoryRestrictedbooleanOptional

Defines if the coupon has category restrictions.

Info: Cannot be combined together with the segment restrictions.

Default: false

segmentRestrictedbooleanOptional

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.

Default: false

issuedTostringOptional

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

Responses

200

The coupon has been successfully updated.

400

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

application/json

401

Example response

application/json

403

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

application/json

404

The requested resource does not exist.

application/json

409

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

application/json

500

Some server side error occurred.

application/json

put

PUT /coupon/{tenant}/coupons/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 459

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

No content

Partially updating the coupon by code

patch

Partially updates an existing coupon.

The endpoint was previously available under the /coupon-v2/ base path.

Required scopes

coupon.coupon_manage

Authorizations

Path parameters

codestringRequired

Code of a coupon

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Body

Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.

namestringOptional

Coupon name.

descriptionstringOptional

Coupon description.

discountTypestring · enumOptional

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

Possible values:

discountPercentagenumber · max: 100Optional

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

allowAnonymousbooleanOptional

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

Default: false

maxRedemptionsnumberOptional

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

Default: -1

maxRedemptionsPerCustomernumberOptional

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

Default: -1

discountCalculationTypestring · enumOptional

Determines whether the coupon is applied to the total or subtotal value of the order.

Default: SUBTOTALPossible values:

categoryRestrictedbooleanOptional

Defines if the coupon has category restrictions.

Info: Cannot be combined together with the segment restrictions.

Default: false

segmentRestrictedbooleanOptional

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.

Default: false

issuedTostringOptional

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

Responses

200

The coupon has been successfully updated.

400

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

application/json

401

Example response

application/json

403

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

application/json

404

The requested resource does not exist.

application/json

409

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

application/json

500

Some server side error occurred.

application/json

patch

PATCH /coupon/{tenant}/coupons/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 459

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

No content