Developer Docs — API Reference

Authentication

Authorize

Exchanges your API key and secret for an access token. Send the token as Authorization: Bearer {accessToken} on every other call.

Wecheer issues one apiKey, apiSecret and advertiserId per brand and per environment. Keep them on your server only.

POST{user-management-base-url}/api/advertiser/v1/authorize

Base URL

Environment	User management base URL
Staging	`https://api.wecheer.me/staging-usermanagement`
Production	`https://api.wecheer.me/usermanagement`

Headers

Header	Value	Required
`apiKey`	Your API key	Yes
`apiSecret`	Your API secret	Yes
`Content-Type`	`application/json-patch+json`	Yes

Body

Field	Type	Required	Description
`advertiserId`	string	Yes	Your brand’s ID on Wecheer, shared at onboarding.

cURL

curl -X POST 'https://api.wecheer.me/staging-usermanagement/api/advertiser/v1/authorize' \
  -H 'accept: text/plain' \
  -H 'apiKey: YOUR_API_KEY' \
  -H 'apiSecret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{ "advertiserId": "YOUR_ADVERTISER_ID" }'

Response

JSON · 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "advertiserId": "YOUR_ADVERTISER_ID"
}

Status	Meaning
`200`	Success. The body holds the access token.
`400`	The request is invalid, for example a missing `advertiserId`.
`401`	The API key or secret is wrong.

Consumptions

Consumption object

One action in your system that can reward a user, with one or more lines.

JSON

{
  "consumptionId": "I198037776491223",
  "consumptionDate": "2026-04-25T12:34:00Z",
  "identifiers": [
    { "key": "userId", "value": "user-uuid-12345" },
    { "key": "phoneNumber", "value": "40720005123" },
    { "key": "email", "value": "user@example.com" }
  ],
  "consumptionLines": [
    { "sku": "example_sku_product_a", "quantity": 1 }
  ]
}

Field	Type	Required	Description
`consumptionId`	string	Yes	The ID of the action in your system. Must be unique: each ID is processed once, and a repeat returns `409`.
`consumptionDate`	string	Yes	When the action happened, in ISO 8601 UTC, for example `2026-04-25T12:34:00Z`.
`identifiers`	array of Identifier	Yes	Who to reward. Send at least one. `userId` is the most reliable match.
`consumptionLines`	array of Line	Yes	What happened. Send several lines for a basket with several products.

Identifier

Field	Type	Required	Description
`key`	string	Yes	One of `userId`, `phoneNumber`, `email`.
`value`	string	Yes	The Wecheer user ID, phone number or email.

Line

Field	Type	Required	Description
`sku`	string	Yes	The SKU set up for this trigger in the campaign.
`quantity`	number	Yes	Number of units. Use `1` for actions such as a poll answer or a review.
`productName`	string	No	A readable name for the line. Defaults to the SKU.

Create consumption

Sends one consumption to reward a user.

POST{campaigns-base-url}/api/advertiser-integration/v1/consumption

Base URL

Environment	Campaigns base URL
Staging	`https://api.wecheer.me/staging-campaigns`
Production	`https://api.wecheer.me/campaigns`

Headers

Header	Value	Required
`Authorization`	`Bearer {accessToken}`	Yes
`Content-Type`	`application/json-patch+json`	Yes

cURL

curl -X POST 'https://api.wecheer.me/staging-campaigns/api/advertiser-integration/v1/consumption' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "consumptionId": "I198037776491223",
    "consumptionDate": "2026-04-25T12:34:00Z",
    "identifiers": [ { "key": "userId", "value": "user-uuid-12345" } ],
    "consumptionLines": [ { "sku": "example_sku_product_a", "quantity": 1 } ]
  }'

Responses

Status	Meaning
`200`	Consumption accepted.
`400`	Request invalid: missing `consumptionId`, identifiers or body.
`401`	Token missing or expired.
`404`	User not registered, or user hasn’t joined the campaign.
`409`	Consumption already processed.
`500`	Error on Wecheer’s side.

SSO

OpenID Connect setup

SSO is configured with your Wecheer contact, not through an API call. This is what each side provides. How the login works is described in the SSO guide.

Configuration values

Value	Provided by	Notes
Redirect URL	Wecheer	One for staging and one for production. Register both in your CIAM.
Issuer URL	You	The OpenID Connect issuer of your Microsoft CIAM tenant.
Client ID and client secret	You	For the application you registered for Wecheer, per environment.
SSO on or off	Wecheer	Set per campaign.

User data in the token

Claim names differ between tenants, so we map them with you during setup.

Data	Required	Used for
Unique user ID	Yes	Links the Wecheer profile to your user.
Phone number	At least one of the two	Recommended identifier. Verify it at sign-up.
Email	At least one of the two	Identifier when there is no phone number.
First name, last name	No	Fills the Wecheer profile.
Language	No	Shows Wecheer in the user’s language.
Marketing consent	No	Sets the user’s opt-ins on Wecheer.

Events

Event envelope

Events Wecheer shares with you through Segment or a webhook. All use the standard Segment track structure. Event names are case-sensitive: use them exactly as listed.

JSON

{
  "type": "track",
  "event": "EventName",
  "userId": "user-uuid-12345",
  "timestamp": "2026-01-15T12:34:56.789Z",
  "properties": { },
  "context": { "source": "wecheer", "version": "1.0" }
}

Consumption events

Event	Sent when
`any_consumption`	A QR code is scanned or a receipt is validated
`first_consumption`	The user’s first consumption in a campaign
`consumption_match_item`	A receipt item matches the campaign rules
`points_received`	Points are added to the user
`PunchcardStampsReceived`	Stamps are added to a punch card
`punchcard_step_completed`	A punch card milestone is reached
`card_received`	The user receives a campaign card
`CheercoinsUpdated`	The user’s Cheercoins balance changes

Example: `points_received`

JSON

{
  "type": "track",
  "event": "points_received",
  "userId": "user-uuid-12345",
  "timestamp": "2026-01-15T12:34:56.789Z",
  "properties": {
    "eventId": "evt-uuid-12345",
    "campaignId": "camp-12345",
    "points": 150,
    "reason": "product_scan",
    "previousBalance": 1000,
    "newBalance": 1150
  }
}

User events

Event	Sent when
`user_created`	A new user registers
`user_updated`	Profile details change
`user_data_shared`	The user shares data with a campaign
`UserChannelSubscriptionChanged`	Communication preferences change

Reward events

Event	Sent when
`RewardCreated`	A reward is added to the catalog
`CatalogRedeem`	A user redeems a catalog reward. Includes the voucher code.
`Redeem Reward Started`	A redemption starts
`Redeem Reward Failed`	A redemption fails

Example: `CatalogRedeem`

JSON

{
  "type": "track",
  "event": "CatalogRedeem",
  "userId": "user-uuid-12345",
  "properties": {
    "redemptionId": "redeem-uuid-12345",
    "rewardId": "reward-uuid-12345",
    "rewardName": "Digital voucher",
    "cost": { "points": 500 },
    "voucherCode": "VOUCHER-ABC123"
  }
}

Reference

Status codes

What to do with each code is explained in Errors and retries.

Code	Status	Meaning
`200`	OK	The request succeeded.
`400`	Bad Request	The request is malformed or missing a required field.
`401`	Unauthorized	Credentials or token are missing, wrong or expired.
`404`	Not Found	The user or resource doesn’t exist.
`409`	Conflict	Duplicate, for example a `consumptionId` already processed.
`429`	Too Many Requests	Rate limit reached.
`500`	Internal Server Error	Unexpected error on Wecheer’s side.

Coming soon

In development

These APIs are on our roadmap. They will move into this reference, with a Changelog entry, when they are released.

Accounts In development

Create a Wecheer profile, with opt-ins, from your backend.

Reward redemptions In development

Check a reward code from your checkout, in store or online, and mark it as used.

Authorize

Base URL

Headers

Body

Response

Consumption object

Identifier

Line

Create consumption

Base URL

Headers

Responses

OpenID Connect setup

Configuration values

User data in the token

Event envelope

Consumption events

Example: points_received

User events

Reward events

Example: CatalogRedeem

Status codes

In development

Accounts In development

Reward redemptions In development

Example: `points_received`

Example: `CatalogRedeem`