Transaction lifecycle#

The Antavo Enterprise Loyalty Cloud has been designed to work in close harmony throughout the product purchasing lifecycle. Every transactional element can be correlated with an Antavo event and is considered a major event for an active points loyalty scheme. This document shows how this connection can be made in a modern realistic environment for both an online and offline/physical shop.

The bidirectional synchronization of real-time loyalty data from the Antavo Enterprise Loyalty Cloud means that the transactional process can be accurately tracked and can also instantaneously add in-store value for the customer. Every transactional process is unique to each client’s existing protocol but there are some major common phases within transaction management/lifecycle.

Customer identification#

In an online environment, the loyalty identity of a customer is relatively easy to monitor as it usually mirrors the e-commerce account. Thus, active customers logging into a shopping environment with the correct credentials can result in the associated e-commerce account being linked to the corresponding loyalty scheme account. Antavo recommends that this linking process occurs via a referring number scheme to avoid the risk of exposing e-commerce account details.

Offline identification occurs at the cashier typically with a Membership pass. This identifier can be transmitted to the cashing system using various methods: mobile NFC transfer; scanning of a membership QR code stored in an electronic wallet or as part of a standard mobile application or by scanning a physical loyalty card. Membership can also be selected using a selection of personal details provided to and entered by the cashier into an EPOS.

Successful customer identification enables the customer to access additional loyalty-based options and for vendors to tailor the retail experience during the purchase. These real-time features may include:

  • Special offers

    • Tier specific promotions

    • In-store benefits

    • Bonus loyalty specific deals

  • Burning of points at checkout

  • Coupon redemption

Purchasing#

A purchase event can be instantaneously submitted to the Antavo loyalty scheme using an EPOS. Off-line schemes have the option of uploading purchasing events in bulk outside of operational hours. However, these bulk uploads remove the instantaneous update of Antavo and may affect the program’s performance with customers.

Purchases data can be sent directly from ecommerce systems using the Antavo Events API during the checkout progress. Omnichannel business with physical stores can also connect your EPOS machine to the Antavo Enterprise Loyalty Cloud via a direct integration, where possible, and also using the Antavo Events API. There are some typical purchase submission scenarios:

Instantaneous:

The customer is awarded the points after a successful purchase but before the completion of a transaction.This method only works if the loyalty program does not need purchase acceptance

Post invoiced/shipped:

Customers only receive upon the final completion of the whole transaction.

In store:

Customers are instantaneously awarded points after product(s) purchasing in the physical store.

Post Purchase:

Options including purchase refunding and the subsequent removal of awarded points and the printing of a customer point summary on a receipt.

The following events are the main steps which are used in integrations and manual solution for the journey from purchase to points.

Checkout#

The checkout event is used to send purchase information to Antavo. A successful checkout event will update the customers purchase histories and trigger any loyalty-based logic operations. Once a checkout event is created, it can not be modified in any way but the effects of the event can be mitigated by submitting a second counteracting event. The standard event contains the following details and each of these is explained in more details in the Event API page section.

Note

The Incentivized Purchase/Points Economy module can only calculates the number of points using a checkout_item. All transactions must include at least one line item in order for this functionality to work. Any additional information submitted in the top-level checkout event is purely informative.

transaction_id:

A unique identifier for the transaction.

total:

The purchase total.

points_burned:

The number, if any, of point used in the transaction as a discount.

Individual itemization of products:

An array of checkout items.

Note

The checkout_item event automatically inherits all Checkout attributes.

The creation of a custom attribute in checkout and the checkout_item event results in the checkout_item attribute inheriting the checkout value.

Examples#

Request

POST /events
Host: api.<region>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc

{
    customer: "unique_customer_id",
    action: "checkout",
    data: {
        transaction_id: "unique_transaction_id",
        total: 100,
        points_burned: 0,
        items: [
            {
                product_id: "product_id",
                product_name: "name_of_the_product",
                product_url: "webstore_url_of_product",
                price: 50,
                quantity: 1,
                discount: 0,
                subtotal: 50,
                points_rewarded: 0
            },
            {
                product_id: "product_id",
                product_name: "name_of_the_product",
                product_url: "webstore_url_of_product",
                price: 50,
                quantity: 1,
                discount: 0,
                subtotal: 50,
                points_rewarded: 0
            },
        ]
    }
}

Expansions#

Antavo have an extensive range of modules which can be rapidly deployed to provide new functionality. The following modules expand the checkout functionality and can be easily installed. Please contact your customer success manager to enable any of these modules within your system.

Checkout accept:

This module only provide an approval mechanism for purchases. Acceptance/rejection can be processed manually. Checkout events can be also be automatically accepted after a specified number of days.

Coupon:

This module enables coupon pools and also adds the ability for the checkout event to automatic redeem any voucher codes included in the submission.

Customer ID validation:

This modules enables the creation of guest checkouts and subsequent claiming of the transaction by full members

Product catalog:

This enables the correlation of purchased items to be linked with an detailed uploaded list of all products, increase the information available through the Antavo Enterprise Loyalty Cloud.

Pending:

This module provide an approval mechanism for creating pending events from any event, including checkout events.

Stores:

This adds a store property to the checkout which can be used with store module to track the location of purchases.

Checkout accept#

The enablement of the checkout_accept module provides an additional verification step between the submission of a checkout event and the subsequent writing and application of the event to the target customer. This pending state is recorded within Antavo for the customer – any awarded points will be stored as pending points and no purchase information. The pending checkout can be automatically accepted or rejected after given timewindow, depending upon the enabled module, and can also be manually accepted, rejected or modified with the following three commands:

checkout_accept:

The submission of this event with the corresponding transaction id results in the purchasing information and pending points being assigned to the customer, triggering all Antavo logic processes.

checkout_reject:

This event rejects the pending checkout event and no changes are made to the customer.

checkout_update:

This event enables data within the pending event to be updated before the pending event is accepted/rejected. The checkout_update event can be used to override the auto_accept date of the transaction but only by using the modify channel of a suitable workflow.

Note

checkout_accept and checkout_update and their corresponding item events can automatically inherit data from the corresponding checkout/checkout_item event. Custom checkout attributes need to be created in to ensure that the all checkout/checkout_item fields are correctly inherited.

Draft transactions#

The submission of any event with a unique transaction_id results in the creation of a draft transaction. This incomplete transaction can be updated by submitting a valid checkout event with the same transaction_id. This causes the transaction to start the normal lifecycle and results in status change to accepted or pending if the Checkout accept module is enabled.

Example draft transaction response from /customers/{customer_id}/transactions/{transaction_id}#
{
   "id": "09270927-1",
   "status": "draft",
   "created_at": "2022-09-27T16:43:36+02:00",
   "updated_at": "2022-09-27T16:43:36+02:00",
   "total": 0,
   "refunded": 0,
   "items": [],
   "earned": 0,
   "burned": 0
}

Guest checkout#

Checkouts can be recorded in Antavo for guest customers. These events can be be later claimed by the customer when they have become a full loyalty members.

Guest checkout events can be submitted by using a standard checkout event with the customer field replaced with guest field, value true. Standard checkout and checkout_item fields can be used.

{
 "action": "checkout",
 "guest": "true",
 "data": {
     "transaction_id": "deathstarplans",
     "total": 1000,
     "shipping": 1000,
     "items": [
         {
             "product_id": "R2D2",
             "product_name": "astromech droid",
             "price": 1000.78,
             "subtotal": 1000.78,
             "quantity": 1
         }
     ]
 }
 }

Guest checkout can be claimed using the checkout_claim event.

{
    "action": "checkout_claim",
    "customer": "ob1",
    "data": {
        "transaction_id": "deathstarplans"
    }
}

Note

This function requires the Customer ID Validation module to be enabled and with guest events checked.

Pending events#

The pending events module provides a general additional verification step for any Antavo events, including checkouts. This functionality is further discussed in the user manual. The main approval events are listed below:

pending_validate:

Validate a pending event

pending_invalidate:

Invalidate a pending event

Refunds#

Antavo provides the refund event as a mechanism for reversing a checkout event. The refunding process removes the transactionID from the database and restores the pre-purchase purchase_total, purchase_count and point balances.

The only information required for submitting this event is the corresponding transaction_id and the pre-transaction state will be restored.

transaction_id:

A unique identifier for the transaction to be refunded

Note

Only transactions with an accepted status can be refunded.

Points Assignment#

Points relating to spending activities are calculated instantaneously upon Antavo receiving the corresponding checkout event. This functionality is provided by the Incentivized purchase module. This module is enabled automatically in the loyalty program; can be configured on the Antavo Enterprise Loyalty Cloud and provides the base exchange rate between purchases and awarded points.

The provided functionality can be expanded and overwritten using custom rules in the Antavo Rule editor. Also, custom points can be rewarded for particular particular purchase by using the points_rewarded property in the checkout_item action. This results in the stated value being used instead of the calculated value. A full description of the set-up and configuration can be found the in user manual.