Loyalty campaigns

A campaign defines actions a customer can complete to earn rewards. Public variants show campaign details; customer variants can include personal progress and eligibility.

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.

Get all loyalty campaigns

Method	URL path	Required access
GET	/api/v1/brand/loyalty/campaigns	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
query	object	optional	—
query.level_id	number	optional	Integer
query.tag	string	optional	Whitespace trimmed; pattern(/^[a-zA-Z0-9_-]+(,[a-zA-Z0-9_-]+)*$/); Maximum (200)
query.type	string	optional	Whitespace trimmed; pattern(/^[a-zA-Z0-9_-]+(,[a-zA-Z0-9_-]+)*$/); Maximum (200)
query.active	boolean	optional	bool()

tag and type accept comma-separated identifiers made of letters, digits, underscores, or hyphens; maximum string length is 200.

Example:

curl -X GET "$BASE_URL/api/v1/brand/loyalty/campaigns" \
  -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/loyalty_campaign_controller.ts:35 → getAllLoyaltyCampaigns; routes: routes/v1/loyalty_campaign_route.ts:293; service: _getAllLoyaltyCampaigns (app/v1/service/loyalty_campaign_service.ts:95).

Get all loyalty campaigns for user

Method	URL path	Required access
GET	/api/v1/user/loyalty/campaigns	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
query	object	optional	—
query.tag	string	optional	Whitespace trimmed; pattern(/^[a-zA-Z0-9_-]+(,[a-zA-Z0-9_-]+)*$/); Maximum (200)
query.type	string	optional	Whitespace trimmed; pattern(/^[a-zA-Z0-9_-]+(,[a-zA-Z0-9_-]+)*$/); Maximum (200)
query.active	boolean	optional	bool()

tag and type accept comma-separated identifiers made of letters, digits, underscores, or hyphens; maximum string length is 200.

Example:

curl -X GET "$BASE_URL/api/v1/user/loyalty/campaigns" \
  -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/loyalty_campaign_controller.ts:88 → getAllLoyaltyCampaignsForUser; routes: routes/v1/loyalty_campaign_route.ts:147; service: _getAllLoyaltyCampaigns (app/v1/service/loyalty_campaign_service.ts:95).

Get loyalty campaigns by tags

Method	URL path	Required access
GET	/api/v1/brand/loyalty/campaigns/tag	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/loyalty/campaigns/tag" \
  -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/loyalty_campaign_controller.ts:141 → getLoyaltyCampaignsByTags; routes: routes/v1/loyalty_campaign_route.ts:158; service: _getLoyaltyCampaignsByTags (app/v1/service/loyalty_campaign_service.ts:509).

Get loyalty campaigns by tags with banner

Method	URL path	Required access
GET	/api/v1/brand/loyalty/campaigns/tags-with-banner	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/loyalty/campaigns/tags-with-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/loyalty_campaign_controller.ts:191 → getLoyaltyCampaignsByTagsWithBanner; routes: routes/v1/loyalty_campaign_route.ts:178; service: _getLoyaltyCampaignsByTagsWithBanner (app/v1/service/loyalty_campaign_service.ts:731).

Get loyalty campaigns by tags with banner for user

Method	URL path	Required access
GET	/api/v1/brand/user/loyalty/campaigns/tags-with-banner	Origin + Brand key + Customer

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/user/loyalty/campaigns/tags-with-banner" \
  -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/loyalty_campaign_controller.ts:217 → getLoyaltyCampaignsByTagsWithBannerForUser; routes: routes/v1/loyalty_campaign_route.ts:188; service: _getLoyaltyCampaignsByTagsWithBannerForUser (app/v1/service/loyalty_campaign_service.ts:838).

Get loyalty campaigns by category

Method	URL path	Required access
GET	/api/v1/brand/loyalty/campaigns/category/:categoryName	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
path	object	optional	—
path.categoryName	string	yes	—

Example:

curl -X GET "$BASE_URL/api/v1/brand/loyalty/campaigns/category/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/loyalty_campaign_controller.ts:248 → getLoyaltyCampaignsByCategory; routes: routes/v1/loyalty_campaign_route.ts:199; service: _getLoyaltyCampaignsByCategory (app/v1/service/loyalty_campaign_service.ts:1029).

Get almost completed campaigns

Find campaigns near completion for the event items in the request body.

Method	URL path	Required access
POST	/api/v1/brand/user/loyalty/campaigns/almost-completed	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body	object	optional	—
body.event_item	one of the listed forms	yes	—
body.event_item (form 1)	object	optional	—
body.event_item (form 1).event_type	string	yes	Allowed values ("order")
body.event_item (form 1).order	any JSON value	yes	—
body.event_item (form 2)	object	optional	—
body.event_item (form 2).event_type	string	yes	Allowed values ("scan-auth")
body.event_item (form 2).product	any JSON value	yes	—
body.event_item (form 3)	object	optional	—
body.event_item (form 3).event_type	string	yes	Allowed values ("collectible_id")
body.event_item (form 3).collectible	object	yes	—
body.event_item (form 3).collectible.collectible_id	number	yes	—
body.event_item (form 4)	object	optional	—
body.event_item (form 4).event_type	string	yes	Allowed values ("user_update")
body.event_item (form 4).user	object	yes	—
body.event_item (form 4).user.firstName	string	optional	—
body.event_item (form 4).user.dateOfBirth	string	optional	—
body.event_item (form 4).user.phoneNumber	string	optional	replace(/\D/g , ""); Whitespace trimmed
body.event_item (form 4).user.email	string	optional	Email address; Whitespace trimmed; Converted to lowercase
body.event_item (form 5)	object	optional	—
body.event_item (form 5).event_type	string	yes	Allowed values ("user_login")
body.event_item (form 5).user	object	yes	—
body.event_item (form 5).user.mode	string	optional	—
body.event_item (form 5).user.source	string	optional	—
body.event_item (form 5).user.medium	string	optional	—

Example:

curl -X POST "$BASE_URL/api/v1/brand/user/loyalty/campaigns/almost-completed" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"event_item":{"event_type":"order","order":"example"}}'

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

Source: app/v1/controller/loyalty_campaign_controller.ts:497 → getAlmostCompletedCampaigns; routes: routes/v1/loyalty_campaign_route.ts:209; service: _getAlmostCompletedCampaigns (app/v1/service/loyalty_campaign_service.ts:2221).

Get user claimed discount rewards

Method	URL path	Required access
GET	/api/v1/brand/user/loyalty/campaigns/rewards/claimed	Origin + Brand key + Customer

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/user/loyalty/campaigns/rewards/claimed" \
  -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: redeemed, unredeemed.

Source: app/v1/controller/loyalty_campaign_controller.ts:475 → getUserClaimedDiscountRewards; routes: routes/v1/loyalty_campaign_route.ts:93; service: _getUserClaimedDiscountRewards (app/v1/service/loyalty_campaign_service.ts:1196).

Get loyalty campaign by ID

Method	URL path	Required access
GET	/api/v1/brand/loyalty/campaigns/:id	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
path	object	optional	—
path.id	number	yes	Integer

Example:

curl -X GET "$BASE_URL/api/v1/brand/loyalty/campaigns/1" \
  -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/loyalty_campaign_controller.ts:282 → getLoyaltyCampaignById; routes: routes/v1/loyalty_campaign_route.ts:219; service: _getLoyaltyCampaignById (app/v1/service/loyalty_campaign_service.ts:234).

Get loyalty campaign by ID for user

Method	URL path	Required access
GET	/api/v1/brand/user/loyalty/campaigns/:id	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
path	object	optional	—
path.id	number	yes	Integer

Example:

curl -X GET "$BASE_URL/api/v1/brand/user/loyalty/campaigns/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/loyalty_campaign_controller.ts:312 → getLoyaltyCampaignByIdForUser; routes: routes/v1/loyalty_campaign_route.ts:239; service: _getLoyaltyCampaignByIdForUser (app/v1/service/loyalty_campaign_service.ts:297).

Get campaigns for collectible for user

Method	URL path	Required access
GET	/api/v1/brand/user/loyalty/collectible/:collectible_id/campaign	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
path	object	optional	—
path.collectible_id	number	yes	Integer

Example:

curl -X GET "$BASE_URL/api/v1/brand/user/loyalty/collectible/1/campaign" \
  -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/loyalty_campaign_controller.ts:406 → getCampaignsForCollectibleForUser; routes: routes/v1/loyalty_campaign_route.ts:125; service: _getCampaignsForCollectibleForUser (app/v1/service/loyalty_campaign_service.ts:1877).

Lifecycle

A customer's progress in a campaign is one row with two arrays indexed by step: allowed[i], which the progress engine raises as events arrive, and claimed[i], which a claim raises. A step's state follows from them:

• Locked — progress has not reached the step: User cannot redeem the reward. A non-linear campaign unlocks steps by its own rule rather than in order.
• Ready — allowed[i] is above claimed[i].
• Claimed — on a linear campaign, a second claim is refused with Reward already claimed once claimed[i] catches up with allowed[i]. product campaigns skip that check.
• Periodic campaigns reset every step to zero once the whole cycle is allowed and claimed.

A claim of a promotion reward creates the customer's discount and returns its discountCode; a reward with a cost deducts points. The claim endpoint is on Points, levels and rewards, the progress algorithm in campaign progress tracking, and the journey in the earn-and-spend web flow.

Related pages

• Batch Commerce API overview
• Campaigns
• Implementation notes