Customer info integration

In a Scan & Go experience, identifying the shopper isn’t just about access — it’s about enabling personalization, loyalty benefits, and controlled usage. The Customer Profile API allows retailers to recognize customers when they scan their loyalty card, determine whether they are allowed to use the system and unlock devices, while enriching the shopping journey with personalized data.

This article explains when the Customer Profile API is needed, how it works, and who is typically responsible for setting it up.

How does shopreme personalize the shopper experience?

When a shopper scans their loyalty card at a smart cart, handheld device, or unlocking station, shopreme needs to determine who the customer is and whether they are allowed to start a shopping session.

To achieve this, shopreme offers the Customer Profile API, which allows you to provide information to:

• Identify the customer behind the scanned loyalty card

• Decide whether the device should be unlocked

• Personalize greetings and the UI experience

• Provide loyalty data such as points or status

• Automatically apply eligible coupons

• Influence operational behavior such as spot check probability

This ensures that each shopping session is tailored to the individual customer while maintaining control over access.

How customer profile retrieval works

In simple terms, when the Customer Profile API is enabled, the flow works like this:

• A shopper scans their loyalty card at the device

• shopreme sends a GET /customer-profile request to your system

• Your system evaluates the request and returns customer data to shopreme

Your system can return:

• A customer identifier (required)

• An unlocking decision (allow or deny access, required)

• Customer details such as name or email (optional)

• Loyalty information (ID, type, points balance) (optional)

• Automatically applied coupons (optional)

• A spot check bias value to influence fraud prevention (optional)

• A preferred language/locale (optional)

Based on the response:

• The device is either unlocked or not

• A custom denial message can be shown if access is denied

• The UI is personalized (e.g. greeting with name, "Hi Alex!")

• Coupons and loyalty benefits are applied automatically to the new shopping session

Example response structure

A successful response (HTTP 200) to shopreme includes a customer object like this:

{
  "customerId": "UUID",
  "unlockingDevices": {
    "isAllowed": false,
    "denialMessage": "You lack 400 points, please buy more to earn more points"
  },
  "displayName": "Alex",
  "emailAddress": "alex@email.com",
  "loyaltyInformation": {
    "loyaltyId": "MyLoyalty",
    "loyaltyType": "Loyalty Card",
    "loyaltyPointBalance": 4211
  },
  "spotCheckBias": -30,
  "preferredLocale": "en-US",
  "automaticallyAppliedCouponsIds": [
    { "couponId": "coupon1" },
    { "couponId": "coupon2" }
  ]
}

{
  "customerId": "UUID",
  "unlockingDevices": {
    "isAllowed": false,
    "denialMessage": "You lack 400 points, please buy more to earn more points"
  },
  "displayName": "Alex",
  "emailAddress": "alex@email.com",
  "loyaltyInformation": {
    "loyaltyId": "MyLoyalty",
    "loyaltyType": "Loyalty Card",
    "loyaltyPointBalance": 4211
  },
  "spotCheckBias": -30,
  "preferredLocale": "en-US",
  "automaticallyAppliedCouponsIds": [
    { "couponId": "coupon1" },
    { "couponId": "coupon2" }
  ]
}

{
  "customerId": "UUID",
  "unlockingDevices": {
    "isAllowed": false,
    "denialMessage": "You lack 400 points, please buy more to earn more points"
  },
  "displayName": "Alex",
  "emailAddress": "alex@email.com",
  "loyaltyInformation": {
    "loyaltyId": "MyLoyalty",
    "loyaltyType": "Loyalty Card",
    "loyaltyPointBalance": 4211
  },
  "spotCheckBias": -30,
  "preferredLocale": "en-US",
  "automaticallyAppliedCouponsIds": [
    { "couponId": "coupon1" },
    { "couponId": "coupon2" }
  ]
}

If no customer is found, your system should return:

• HTTP 404 (Not Found)

• No response body required

Key behaviors to consider

• Unlock control:
  The unlockingDevices.isAllowed field determines whether the shopper can start using the device.

• Denial messaging:
  If access is denied, a custom message can be displayed. If none is provided, a default shopreme message is used.

• Loyalty mapping:
  The loyalty information directly corresponds to the scanned card and can be used across pricing, promotions, and analytics.

• Coupon automation:
  Coupons returned in the response are automatically applied to the session.

• Spot check influence:
  The spotCheckBias value (-100 to +100) adjusts how likely the shopper is selected for a spot check.

• Localization:
  The preferredLocale can be used to adjust language settings in the UI.

Who sets this up?

Your Customer Profile API should be accessible via a secure and reliable endpoint with fast response times.

This integration is usually handled by:

• Teams managing loyalty or CRM systems

• Developers responsible for customer identity or loyalty services

• Marketing teams defining coupon and personalization logic

• Platform or backend teams responsible for POS and middleware integration

shopreme provides the expected API schema. Your system must implement a GET /customer-profile endpoint that returns data in the required format.