Getting started

Wecheer integration guide

Connect your app, website, POS, identity provider or CRM to Wecheer. The guides are organised by what you want to do: log users in, validate purchases, deliver rewards and share data.

Wecheer works without any integration. Consumers join a campaign from a link or QR code, validate their purchase with an on-pack QR code, a secret code, a photo of the receipt or a photo of the product, and get their reward in the Wecheer app. Integrations connect Wecheer to the systems you already run, so the experience is smoother for consumers and you get the data in real time. Each integration works on its own, so pick only the ones that fit your setup.

Quickstart

Reward a test user on staging with two API calls.

1. Get your staging credentials. Your Wecheer contact shares your advertiserId, apiKey, apiSecret and a staging campaign link. The campaign already has a test SKU set up.
2. Join the test campaign. Open the campaign link on your phone and log in. Your test user now has a card in the campaign and can receive rewards.
3. Get an access token. Call the Authorize endpoint with your key and secret.
4. Send your first consumption. Send the test SKU for your test user, then open the campaign and check that the points arrived.

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

curl -X POST 'https://api.wecheer.me/staging-campaigns/api/advertiser-integration/v1/consumption' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "consumptionId": "quickstart-0001",
    "consumptionDate": "2026-04-25T12:34:00Z",
    "identifiers": [ { "key": "phoneNumber", "value": "YOUR_TEST_PHONE" } ],
    "consumptionLines": [ { "sku": "YOUR_TEST_SKU", "quantity": 1 } ]
  }'

A 200 means the consumption was accepted. A 404 usually means the test user hasn’t joined the campaign yet: go back to step 2.

Environments

Every brand gets its own credentials for each environment. Build and test on staging, then switch the base URL and credentials to go live.

Keep apiKey and apiSecret on your server only, never in an app, website or public repository. Your Wecheer contact can rotate them at any time.

Identity and login

Login options

Every point and reward belongs to a Wecheer user. Choose how your users log in.

Each brand chooses between Wecheer login and SSO with its own identity provider. You can override it per campaign, for example to keep Wecheer login for a staff programme while consumers use SSO.

SSO with Microsoft CIAM

When SSO is on for a campaign, users sign in and register on your identity provider, not on Wecheer. Wecheer trusts the token your provider issues and creates the Wecheer profile for you.

How the login works

1. The user opens a campaign link or scans a campaign QR code.
2. Wecheer sends the user to your CIAM sign-in page.
3. The user signs in, or creates an account with you.
4. Your CIAM sends the user back to Wecheer with an OpenID Connect token.
5. Wecheer validates the token. If the user is new to Wecheer, we create their profile on the spot, with their opt-ins, and join them to the campaign.

Where SSO is configured

The values we need from your identity team, and the user data the token must carry, are listed in the SSO reference.

User identifiers

For SSO users, the token must carry a phone number or an email, or both. Wecheer uses it to recognise the person. We recommend the phone number.

Wecheer gives every user a Wecheer user ID. We pass it to your system in the redirect link, and it is the most reliable way to match a user when you send purchases.

Account creation API In development

An API to create a Wecheer profile from your backend, with opt-ins, before the user opens Wecheer. It suits partners who already own the sign-up flow and don’t need a full SSO redirect. Ask your Wecheer contact for timing.

Purchase validation

Ways to validate a purchase

Tell Wecheer that a user bought something or took an action, so they earn points, stamps or an instant win.

How the Consumption API works

A consumption is any action in your system that should reward a user: a purchase line, a device registration, a review, a poll answer.

Each consumption carries a SKU, the name of the trigger. When the SKU you send matches a SKU set up in the user’s campaign, Wecheer gives the reward configured for it. Wecheer sets up the SKUs in the campaign with you, so you can add new triggers without code changes on our side.

Before you send

Wecheer gives the reward only when all three are true:

• The user has joined the campaign. They opened the campaign link or QR code and logged in, or SSO created them.
• The consumption is new. Each consumptionId is processed once. Send the same ID again and Wecheer returns 409.
• The user is active. Blocked users don’t receive rewards.

Send purchases by API

1. Get an access token from the Authorize endpoint, using your API key and secret. Reuse it until it expires, then get a new one.
2. Map your products to SKUs. Agree with your Wecheer contact which of your product codes or actions map to which campaign SKUs.
3. Send one consumption per transaction to the Consumption endpoint. Use your own transaction ID as consumptionId, and send one line per product in the basket.
4. Identify the user with the Wecheer user ID when you have it. Otherwise use their phone number or email.
5. Handle the response as described in Errors and retries.

Reward distribution

Ways to deliver rewards

How the consumer gets the reward once they’ve earned it.

Reward redemption API In development

Planned scope: your system, such as a POS, an e-commerce checkout or an app, sends the reward code shown by the consumer. Wecheer checks that it is valid, marks it as used and returns the reward details, such as the product or discount to apply. Talk to your Wecheer contact if you want to pilot it.

Data sharing

Data sharing

Share events between Wecheer and your CRM, CDP or data warehouse, in both directions, through Segment.

Segment is free for Wecheer clients to use for this, connects to more than 450 tools, and is SOC 2 compliant.

All events and their payloads are listed in the event reference.

Segment Source Available

Wecheer sends events into your Segment workspace, ready to route to any destination. No custom code is needed.

1. In Segment, add Wecheer from the Sources catalog and name it, for example Wecheer_Staging and Wecheer_Prod.
2. Copy the source’s write key.
3. In Wecheer, go to Advertiser Settings, then Outbound Events, then Segment, and paste the write key.
4. Choose the events you want to receive and save.
5. In Segment, connect the destinations you need and map the events.

The full setup guide is on the Wecheer page of the Segment catalog. Your Wecheer contact can walk your Segment admin through it on a call.

Example: HubSpot

Add HubSpot as a destination in Segment, select the Wecheer source and log in to HubSpot. Then map events such as points_received, CatalogRedeem and user_created to HubSpot contact properties or custom events. Use Segment’s Event Debugger to check that events arrive.

Segment Function Available

A small JavaScript function that runs in Segment. It receives Wecheer events, applies your logic and forwards them to your endpoint. Create it under Connections, Catalog, Functions, connect it as a destination of the Wecheer source, and test it with sample events before going live.

async function onTrack(event, settings) {
  const payload = {
    eventName: event.event,
    userId: event.userId,
    timestamp: event.timestamp,
    properties: event.properties
  };
  const response = await fetch(settings.destinationUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${settings.apiToken}`
    },
    body: JSON.stringify(payload)
  });
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
}

Webhook Available

Wecheer sends the same events straight to an HTTP endpoint of yours, without a Segment workspace. It suits teams that prefer direct server-to-server delivery. Ask your Wecheer contact to set it up.

Segment Destination Available

Send events to Wecheer from your existing Segment tracking. Instead of calling the Wecheer API, you add Wecheer as a destination in Segment and route the events that should reward users.

Ask your Wecheer contact to set it up. If you don’t use Segment, send events with the Consumption API instead.

Concepts

Campaigns, cards and rewards

The few ideas you need to read the rest of these docs.

A brand on Wecheer is an advertiser. Each advertiser runs campaigns: promotions or loyalty programmes with their own rules, rewards and dates. When a user joins a campaign, they get a card in it. A user without a card can’t earn in that campaign.

Users earn when Wecheer validates a consumption: an on-pack QR code, a secret code, a receipt, a product photo, or a purchase sent by your API call. Depending on the campaign, a consumption gives points, stamps on a punch card, or a chance at an instant win. Points belong to the brand: points earned with one brand stay with that brand.

Users spend points in the campaign’s catalog. A redemption turns points into a reward, such as a digital voucher, an e-gift card or a free product. Each of these steps creates an event that you can receive through data sharing.

Errors and retries

Every consumption has a unique consumptionId, so retries are safe: if a retry reaches Wecheer after the first call was already processed, you get 409 and the user isn’t rewarded twice.

Rate limits

Limits are set per brand. Your Wecheer contact will share yours. When you receive 429, wait before retrying. If a Retry-After header is present, wait that many seconds.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function requestWithBackoff(send, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await send();
    if (response.status !== 429 && response.status < 500) return response;
    const retryAfter = Number(response.headers.get('Retry-After')) || 2 ** attempt;
    await sleep(retryAfter * 1000);
  }
  throw new Error('Retries exhausted');
}

Resources

Who does what

Your systems stay yours. You keep your credentials, your data model and your business logic. Wecheer gives you what you need to move fast and test safely.

SSO

Consumption API

Data sharing through Segment

Go-live checklist

• The full flow works on staging: login, consumption, reward and events.
• You have production credentials from Wecheer, stored on your server only.
• Your code points to the production base URLs.
• Wecheer has set up the production campaign with the same SKUs you tested.
• For SSO: the production redirect URL is registered in your CIAM, and Wecheer has your production client details.
• For Segment: the production source is connected and the right events are selected.
• Your Wecheer contact has confirmed the go-live date with you.

Security and compliance

Glossary

Support

Your Wecheer account manager is your first contact for credentials, campaign setup and technical questions during the integration. Not a client yet? Talk to us.