[go: up one dir, main page]

In-store retail integration

Creating an offline-only or omnichannel loyalty program requires Antavo to communicate with your point-of-sale (POS) system. Depending on your infrastructure, this integration can take multiple forms. Antavo offers APIs to support connecting the POS system of your choice. These APIs enable you to:

  • Enroll customers in the loyalty program.
  • Seamlessly identify customers at the register.
  • Automatically process transactions.
  • Reward in-store transactions.

Infrastructure

To successfully integrate and send transaction data from your Point of Sale (POS) system to the loyalty program provider, Antavo, you'll need a robust infrastructure on your end. This setup collects purchase data and other relevant information from POS devices and transmits it to Antavo, where transactions are registered as checkout events.

Your infrastructure can be built using either cloud-native or mainframe solutions. Let's break down both options:

Cloud-Native Infrastructure

A cloud-native setup is typically more resilient and efficient. In the event of an outage or maintenance, cloud-native systems often have built-in solutions to automatically queue and resend data once the connection is restored. This ensures minimal data loss and a smoother integration experience.

Mainframe Infrastructure

While a centralized mainframe solution can also be used, it requires more manual handling. If there's a network outage or the mainframe undergoes maintenance, you'll need to implement mechanisms to queue the transaction data and send it to Antavo later. This approach can be more complex and less resilient compared to cloud-native solutions.

📘

Note

Regardless of the chosen infrastructure, it's important to note that purchases will be registered in Antavo with the timestamp when they are sent, not the original transaction timestamp.

Human resources

POS system integration requires significant input from the following people:

  • POS System expert: Individual(s) with detailed knowledge of the target POS system.
  • Integration tester: Team member(s) capable of fully testing the integration between the POS and Antavo systems.
  • Store assistants: Personnel who will operate the POS system in-store.

Loyalty enrollment

Customers may conveniently enroll in the program by accessing a mobile-friendly site where they sign up instantly after providing the necessary details.

There is an option for deep integration with a POS system, enabling cashiers to enroll new loyalty scheme customers directly.

Enrollment requests should be then sent via the Antavo Events API.

Request example

POST /events  
Content-Type: application/json; charset="UTF-8"  
{  
    "customer": "a222e90f-2c59-468d-9b81-62f560084379",  
    "action": "opt_in",  
    "data": {  
        "email": "[email protected]",  
        "first_name": "Sally",  
        "last_name": "Thompson",  
    }  
}

Response example

{  
    "events": [  
        {  
            "id": "66797c85eca2e03cc51db357",  
            "action": "opt_in",  
            "points": 10,  
            "expdate": "2024-08-01",  
            "account": {  
                "id": "primary_account",  
                "name": "Primary account"  
        }  
    ]  
}

Customer data management

Antavo constructs a 360-degree customer profile enriched with loyalty data for each customer, allowing Sales associates to create unique and personalized interactions across all stores.

Customer identification

Customers can be identified either by searching in the POS system or by scanning a loyalty membership pass. This pass can be assigned to customers using Antavo’s Wallet solution. The loyalty membership pass contains an encoded form of the customer’s unique identifier or membership number. Scanning the barcode or QR code on the membership pass results in the identifier of the customer which can be used to authenticate and access customer data in store.

Learn more about customer identifiers in the Customers document.

Customers API

The customer profile can be accessed at the POS by calling the Antavo Customer API following a successful customer identification.
Please remember that this request requires API signing.

Request example

GET /customers/{customer_id

Response example

HTTP/1.1 200 OK  
Vary: Accept  
Content-Type: text/javascript  
{  
  "country": "UK",  
  "spendable": 4556,  
  "tiers": [  
    {  
      "points_after_expiration": 815,  
      "name": "Bronze",  
      "threshold": 300,  
      "id": "fashion_tier3",  
      "structure": {  
        "name": "Fashion Journey Tier Structure",  
        "id": "fashion_tiers"  
      },  
      "points": 16287,  
      "since": "2023-06-01T21:43:25+09:30",  
      "expdate": "2023-08-01T00:00:00+09:30"  
    }  
  ],  
  "last_login_at": null,  
  "gender": "female",  
  "birth_date": "1989-05-02",  
  "pending": 32061,  
  "language": "en",  
  "score": 15673,  
  "expired": 0,  
  "updated_at": 1718739663,  
  "referrals": 0,  
  "mobile_phone": "",  
  "nickname": "Sally",  
  "currency": "GBP",  
  "id": "a222e90f-2c59-468d-9b81-62f560084379",  
  "first_name": "Sally",  
  "email": "[email protected]",  
  "spent": 11117,  
  "membership_id": \[],  
  "last_name": "Thompson",  
  "purchase_count": 7,  
  "purchase_total": 656,  
  "referrer": null,  
  "optin_at": 1657106644,  
  "reserved": 0,  
  "accounts": [  
    {  
      "spendable": 2272,  
      "earned": 3077,  
      "expired": 0,  
      "reserved": 0,  
      "pending": 32061,  
      "spent": 805,  
      "name": "Primary account",  
      "burn_rates": [  
        {  
          "amount": 1,  
          "currency": "GBP",  
          "converted_amount": 2272,  
          "unconverted_points": 0,  
          "points": 1  
        },  
        {  
          "amount": 1,  
          "currency": "EUR",  
          "unconverted_points": 0,  
          "converted_amount": 2272,  
          "points": 1  
        }  
      ],  
      "id": "primary_account"  
    }  
  ],  
  "purchase_last_date": "2024-06-19",  
  "properties": {  
    "allergies": "lactose",  
    "stores": [  
      "london_02"  
    ],  
    "last_order_pending_points": 200,  
  },  
  "status": "active"  
}

Webhooks

Configure webhooks, in the Management UI to forward collected data to POS systems. This event-driven messaging mechanism enables low-latency communication, as requests sent by Antavo can be captured, queued, and processed asynchronously.

Webhook example

Below is an example illustrating how a coupon claim can be forwarded via a webhook message:

{  
    "consentGuid": "otrpfk",  
    "voucherCode": "COUPON-123456",  
    "voucherStatus": "claimed",  
    "voucherType": "percentage",  
    "value": "10",  
    "voucherName": "Welcome_10",  
    "expiresAt": "2024-05-16T21:59:00+00:00",  
    "createdAt": "2024-05-02T12:42:58+00:00",  
    "claimedAt": "2024-05-02T12:42:58+00:00",  
    "eventName": "voucher_claimed"  
}

Rewarding purchases with incentives

Antavo assigns loyalty benefits for purchases by processing purchase information submitted through the Events API. Each POS system is unique, but there are two general scenarios for integrating with the Events API:

  • Real-time purchases: The POS or its related subsystems have an internet connection and send API requests directly to Antavo, notifying the loyalty program about purchases in real time.
  • Asynchronous purchases: In this scenario, the POS does not have a real-time connection with any external system, and transactions are processed at fixed intervals, such as hourly or daily. Antavo can still be notified about these purchases through batch API calls and/or daily feeds.

In both cases, ensure that the checkout event is submitted via the Events API. For detailed instructions on submitting checkout events, refer to Actions and Events - Event Sources.

Request example

{  
    "customer": "a222e90f-2c59-468d-9b81-62f560084379",  
    "action": "checkout",  
    "data": {  
            "transaction_id": "5875-9373-2618-7461-9237",  
            "total": 100,  
            "points_burned": 20,  
            "items": [  
            {  
                "product_id": "443",  
                "product_name": "Black jeans",  
                "product_url": "https://www.example.com/black-jeans",  
                "price": 55,  
                "quantity": 1,  
                "discount": 5,  
                "subtotal": 50  
            },  
            {  
                "product_id": "543",  
                "product_name": "Blue jeans",  
                "product_url": "https://www.example.com/blue-jeans",  
                "price": 50,  
                "quantity": 1,  
                "discount": 0,  
                "subtotal": 50  
            }  
        ]  
    }  
}

Response example

{  
    "id": "a222e90f-2c59-468d-9b81-62f560084379",  
    "created_at": 1719252448,  
    "email": "[email protected]",  
    "first_name": "Sally",  
    "last_name": "Thompson",  
    "status": "active",  
    "score": 608,  
    "spent": 0,  
    "expired": 0,  
    "pending": 0,  
    "image_url": null,  
    "spendable": 608,  
    "events": [  
        {  
            "id": "6679b5e4e2ac1e2fa55a04bb",  
            "action": "checkout_item",  
            "points": 50,  
            "expdate": "2025-06-24",  
        },  
        {  
            "id": "6679b5e4e2ac1e2fa55a04bc",  
            "action": "checkout_item",  
            "points": 50,  
            "expdate": "2025-06-24",  
        }  
    ]  
}

The response returns customer information and the registered events.

Point value of items

Antavo provides the Points preview API endpoint that can be called in real-time from the POS to retrieve the point value of the currently selected items. This mechanism can also handle entire carts and display a summarized view of all points to be earned for a purchase.

For more detailed information about this option, refer to the Transactions document.

Using loyalty program benefits in-store

Customers can use earned benefits (points, coupons, offers) to receive discounts on their purchases. The available benefits can be retrieved from Antavo via API and displayed to the cashier at the register. Usage information can also be forwarded to Antavo by sending API requests from the POS.

For detailed instructions on using Antavo’s endpoints for each scenario, refer to the following: