Shopify rewards and gift cards

Redeem loyalty points through Shopify gift cards or product rewards, view issued gift cards, and refund eligible gift-card value.

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.

Fetch Shopify gift cards

Method	URL path	Required access
GET	/api/v1/brand/shopify-gift-cards	Origin + Brand key

Request fields: no body, query, or path fields are read by this controller. Context comes from the headers/middleware above.

Example:

curl -X GET "$BASE_URL/api/v1/brand/shopify-gift-cards" \
  -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/shopify_controller.ts:13 → fetchShopifyGiftCards; routes: routes/v1/shopify_route.ts:100; service: _fetchShopifyGiftCards (app/v1/service/shopify_service.ts:59).

Redeem Shopify gift card

Method	URL path	Required access
POST	/api/v1/user/gift-card/redeem	Origin + Brand key + Customer

Request fields:

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

Example:

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

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: code, amount, note.

Source: app/v1/controller/shopify_controller.ts:24 → redeemShopifyGiftCard; routes: routes/v1/shopify_route.ts:110; service: _redeemShopifyGiftCard (app/v1/service/shopify_service.ts:75).

Redeem product with points

Redeem selected products using loyalty points in the Shopify integration.

Method	URL path	Required access
POST	/api/v1/user/gift-card/redeem-product	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.product_ids	array of number	yes	Minimum (1)

Example:

curl -X POST "$BASE_URL/api/v1/user/gift-card/redeem-product" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"product_ids":[1]}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: discounts, points.

Source: app/v1/controller/shopify_controller.ts:57 → redeemProductWithPoints; routes: routes/v1/shopify_route.ts:120; service: _redeemProductWithPoints (app/v1/service/shopify_service.ts:221).

Fetch gift cards by user ID

Method	URL path	Required access
GET	/api/v1/user/shopify-gift-cards	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
query.limit	string	optional	No controller schema
query.offset	string	optional	No controller schema

limit defaults to 10 and offset to 0 via Number(value) || default.

Example:

curl -X GET "$BASE_URL/api/v1/user/shopify-gift-cards?limit=example&offset=example" \
  -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. Result fields/details: total, limit, offset, gift_cards.

Source: app/v1/controller/shopify_controller.ts:123 → fetchGiftCardsByUserId; routes: routes/v1/shopify_route.ts:130; service: _fetchGiftCardsByUserId (app/v1/service/shopify_service.ts:435).

Refund Shopify gift card

Refund an unused Shopify gift-card balance into loyalty points.

Method	URL path	Required access
POST	/api/v1/user/gift-card/refund	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.gift_card_id	string	yes	—

Example:

curl -X POST "$BASE_URL/api/v1/user/gift-card/refund" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"gift_card_id":"<GIFT_CARD_ID>"}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: points_refunded, balance_refunded.

Source: app/v1/controller/shopify_controller.ts:92 → refundShopifyGiftCard; routes: routes/v1/shopify_route.ts:139; service: _refundShopifyGiftCard (app/v1/service/shopify_service.ts:336).

Related pages

• Batch Commerce API overview
• Implementation notes