Discounts and coupons

Find available offers, evaluate offers for a shopping bag, and associate eligible discounts with the customer.

Access labels such as Origin + Brand key + Customer are defined in Headers and access. Each endpoint ends in a Try it console; set the host and keys once in its Settings tab or on the overview.

A discount is the platform's single offer entity (a discount row); there is no separate coupon object on the storefront API.

Show all discount banner

Method	URL path	Required access
GET	/api/v1/discount/banner	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
query.hubId	number	optional	—

Example:

curl -X GET "$BASE_URL/api/v1/discount/banner" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:16 → showAllDiscountBanner; routes: routes/v1/discount_route.js:10; service: _showAllDiscountBanner (app/v1/service/discount_service.js:19).

Assign a one-time discount to the customer

Adds the discount to a verified customer as a one-time-use promotion (_createPromotionForUser). Although the method is GET, the call writes; do not prefetch it.

Method	URL path	Required access
GET	/api/v1/discount/reward/:discountId	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
path.discountId	number	yes	—

Example:

curl -X GET "$BASE_URL/api/v1/discount/reward/1" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:45 → createPromotionForUser; routes: routes/v1/discount_route.js:130; service: _createPromotionForUser (app/v1/service/discount_service.js:905).

Get all user rewards

Method	URL path	Required access
GET	/api/v1/user/discount/reward	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
query.includeExpired	boolean	optional	Default (false)

includeExpired is true only when the query value is the string true or the boolean true. It defaults to false.

Example:

curl -X GET "$BASE_URL/api/v1/user/discount/reward" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:292 → getAllUserRewards; routes: routes/v1/discount_route.js:140; service: _getAllUserRewards (app/v1/service/discount_service.js:2115).

Get applicable discounts

Method	URL path	Required access
POST	/api/v1/discount/applicable	Origin + Brand key
POST	/api/v1/user/discount/applicable	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	optional	—
body.payload.bag	array of object	optional	Default ([ ])
body.payload.bag[].isPromotional	boolean	optional	—
body.payload.bag[].index	number	optional	—
body.payload.bag[].hubProductId	number	yes	—
body.payload.bag[].quantity	number	yes	—
body.payload.bag[].packageId	string	optional	Whitespace trimmed
body.payload.addressId	number	optional	—
query.hubId	string	optional	No controller schema
query.roomId	string	optional	No controller schema
query.userId	string	optional	No controller schema

A hub must be available in the tenant key or hubId query. Without an authenticated user, provide a non-empty bag. tenant hubId/roomId and authenticated userId take precedence over query values.

Example (first URL):

curl -X POST "$BASE_URL/api/v1/discount/applicable" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:78 → getApplicableDiscounts; routes: routes/v1/discount_route.js:120; service: _getApplicableDiscounts (app/v1/service/discount_service.js:652).

Get products for discount

Method	URL path	Required access
GET	/api/v1/discount/:discountCode	Origin + Brand key + Hub selected

Request fields:

Field	Type	Required	Rules / meaning
path.discountCode	string	yes	Whitespace trimmed

Example:

curl -X GET "$BASE_URL/api/v1/discount/example" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:153 → getProductsForDiscount; routes: routes/v1/discount_route.js:60; service: _getProductsForDiscount (app/v1/service/discount_service.js:956).

Get discount by discount code

Method	URL path	Required access
GET	/api/v1/discount/detail/:discountCode	Origin + Brand key
GET	/api/v1/user/discount/detail/:discountCode	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
path.discountCode	string	yes	Whitespace trimmed
query.userId	number	optional	—

Example (first URL):

curl -X GET "$BASE_URL/api/v1/discount/detail/example" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:186 → getDiscountByDiscountCode; routes: routes/v1/discount_route.js:89; service: _getDiscountByDiscountDetails (app/v1/service/discount_service.js:1311).

Check and create user discount

Method	URL path	Required access
POST	/api/v1/user/discount/check-user-discount	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.discountId	number	yes	—

Example:

curl -X POST "$BASE_URL/api/v1/user/discount/check-user-discount" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"discountId":1}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/discount_controller.js:259 → checkAndCreateUserDiscount; routes: routes/v1/discount_route.js:99; service: _checkAndCreateUserDiscount (app/v1/service/discount_service.js:2051).

Related pages

• Earn-and-spend flow (web)
• Batch Commerce API overview
• Creating promotions
• Gift cards and promo codes
• Implementation notes