Transactions

In most loyalty programs, incentivizing purchases is key. Whether it's awarding points, organizing tiers based on money spent, or providing instant rewards after purchases, the goal is to keep customers coming back to make purchases.

Transactions lie at the heart of the Antavo Engine, seamlessly integrating with every stage of the product purchasing lifecycle. Each transactional stage can be linked with specific Antavo events, forming a crucial relationship between transactions and events. This guide demonstrates how transactional data submission works within a loyalty program.

The checkout event, describing the transaction details, is the cornerstone of transaction handling.

In point-based loyalty schemes, the Incentivized purchase module (or Earn rules if Points Economy is enabled) determines how the system processes this checkout event, providing the necessary functionality for transaction handling. It ensures that the checkout event is handled by the system as expected, allowing customers to initiate the transaction process and receive the associated benefits seamlessly.

Let's dive into the process of transaction handling and its key steps. Additionally, we'll explore extra options to extend this process as needed.

📘

Note

Antavo’s event-handling rules apply to transaction-related events as well. Detailed information about event handling can be found in the Actions and Events documentation.

Customer identification

To register the checkout event with the appropriate customer profile in Antavo, you first need to identify the customer who makes the purchase. This means the event must include a customer attribute for identification.

As detailed in the Customers document, Antavo recommends that customers have a separate loyalty ID linked to their loyalty program profile. This ensures both security and data integrity.

• Consistency: The loyalty ID ensures that transactional data, from various sources - e-commerce, POS, or data imports - are correctly attributed to the customer.
• Flexibility: You can also use external IDs. This allows transactional data from sources that do not use the loyalty ID to still be associated with the correct loyalty program member.

For more details on using identifiers in the loyalty program, refer to the Customers document. External ID usage is also covered in a dedicated section.

Online identification

In an online store, customers identify themselves by logging into their profiles. Once logged in, the e-commerce system must ensure that the loyalty ID (or a configured external ID) is used when submitting the checkout event.

Offline identification

Offline identification typically happens at the cash register. This can be done through traditional methods like scanning a physical loyalty card, or the cashier entering personal details provided by the customer into the POS.

However, a more convenient method, the mobile pass is available now. A membership QR code or barcodes stored in the customers' mobiles (Apple Wallet or Google Wallet) can be scanned for identification. Antavo’s Wallet module can generate module passes for offline identification. To learn more about Antavo’s passes, check the Wallet module user manual.

📘

Note

Sometimes a customer might not be identifiable at the moment of the transaction - maybe they forgot their card or mobile at home or placed an online order without logging in. In these cases, a transaction can be registered as a guest checkout, which customers can later claim.
Information on how to process and claim guest checkouts can be found in this section.

Transaction lifecycle

Transaction registration

Offline transactions can be submitted instantly to the loyalty program using a POS system at the time of checkout. Alternatively, there’s also an option to upload purchasing events in bulk outside of operational hours.

For more datails on in-store integrations, visit the relevant section in our documentation.

Online purchase data can be sent directly from e-commerce systems when the order is submitted via API calls or direct integration. In this document, you’ll find detailed information on the API calls to be implemented, or refer to the e-commerce integration documents to learn more about Antavo’s built-in integrations.

📘

Note

You can also submit draft transactions. Details on handling draft transactions can be found later in this document.

To register a transaction, you need to submit the checkout event to Antavo in all cases.

A successful checkout event triggers any loyalty-based logic operations configured in the Management UI and updates the following:

• customer's purchase history
• the built-in attribute values: purchase_total, purchase_count, purchase_last_date, purchase_first_date, purchase_avg_total, purchase_avg_items
• attributes of the Purchases data extension

If you are working with a point-based loyalty scheme, the ratio at which points should be awarded has to be specified in the Incentivized purchase module (or Earn rules if Points economy is enabled) configuration page.
The customer’s point-related attribute values (score, spent, spendable) are recalculated automatically when the transaction is registered.

If the program does not handle points, set the related value to 0 on the module configuration page.

Pending period

If you prefer to wait until the end of the return period before assigning benefits for purchases, use the Checkout accept module. This approach helps prevent potential exploitation of the loyalty program and ensures rewards are only given for completed and confirmed transactions.
Implementing a pending period increases the complexity of the transaction lifecycle, but helps maintain program fairness and protects the business from fraudulent activities.

Pending state

No information about the transaction is registered to the customer until the pending checkout is either accepted or rejected. Purchases can be updated as many times as necessary during the pending period by submitting checkout_update events. During the pending state, awarded points (in point-based programs) are stored as pending points in the pending customer attribute. This attribute may also be updated based on checkout_update events.

Acceptance and rejection

Transaction acceptance or rejection can be processed manually, or checkout events can be automatically accepted or rejected after a specified time period, based on the configuration of the Checkout accept module in the Management UI.

The auto-accept date, when the transaction is automatically accepted or rejected, is stored in the auto_accept attribute and is automatically saved to the checkout event based on the settings. This can be overridden by specifying a value when submitting the checkout event or using the checkout_update event through the modify branch of a suitable workflow.

When acceptance or rejection occurs, the checkout_accept or checkout_reject event is logged, respectively. A transaction can be accepted or rejected even before the auto-accept date by submitting the appropriate event via the Events API or manually on the Management UI.

The checkout_reject event invalidates the pending checkout event and reverts pending points (if any).

Handling refunds

Refunds can be administered in the loyalty program after a purchase is completed, allowing you to reverse the benefits rewarded for the transaction. Refunds can be processed regardless of whether there was a pending period applied for the checkout event. However, if there was a pending period, only transactions with an accepted status can be refunded.
Use the refund event to handle refunds. It restores the customer’s pre-purchase state, including purchase_total and purchase_count customer attribute values, and point balances.

🚧

Note

Please note that some benefits awarded for the transactions are not automatically revoked. You need to submit a reward_revoke or coupon_invalidate event separately.

Partial refunds

Partial refunds can also be processed, via a partial_refund or refund_item event, where only a portion of the transaction is returned. This allows more flexibility in managing customer returns and maintaining accurate records of their purchase history and point balance.

📘

Note

The response provided by the Events API when submitting any refund-related event includes the number of points removed from the customer’s account as a result of the refund. This information can be integrated into your receipt printing system to appear on receipts printed in offline stores.

Implementation of API events

The Incentivized purchase module (or Earn rules if Points economy is enabled) module settings allow choosing between item-level or transaction-level transaction processing, which determines the type of API events to be used.

Item-level transaction lifecycle

Item-level processing enables granular control throughout the transaction lifecycle, facilitating item-specific handling at each stage.

Transaction registration

When handling transactions at the item level, the checkout event and its child events, checkout_item events, are used to register purchase information in the database using the Events API.

Within the checkout event, provide an array of items, that Antavo will translate into a separate checkout_item events. The checkout_item event inherits all attributes from the checkout event. If you add the same custom attribute to both events, the checkout_item attribute will inherit the submitted value of the checkout attribute.

🚧

Note

Sending separate checkout_item events will not yield the same results as sending an array of items in the checkout event and Antavo translating it into separate events.

Points assigned for the transaction are populated by Antavo in the points_rewarded attribute of the registered event. By submitting the checkout event with pre-filled points_rewarded value, Antavo will use the custom values provided and will not perform any calculations if no pending mechanism is applied.

Here’s a standard checkout event example if the checkout is administered on the item level. You can find detailed information on this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,  
SignedHeaders=date;host,  
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
    "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
    "action": "checkout",  
    "data": {  
        "transaction_id": "1703545579",  
        "total": 150,  
        "points_burned": 10,  
        "items": [  
            {  
                "product_id": "001",  
                "product_name": "Super Cool T-Shirt",  
                "product_url": "https://www.example.com/products/super-cool-tshirt-001",  
                "price": 50,  
                "quantity": 2,  
                "discount": 5,  
                "subtotal": 95,  
                "points_rewarded": 20  
            },  
            {  
                "product_id": "002",  
                "product_name": "Stylish Jeans",  
                "product_url": "https://www.example.com/products/stylish-jeans-002",  
                "price": 55,  
                "quantity": 1,  
                "discount": 5,  
                "subtotal": 50,  
                "points_rewarded": 10  
            },  
        ]  
    }  
}

📘

Note

In point-based loyalty schemes, points are assigned based on the subtotal value of each checkout_item event separately.

Pending period

Checkout update event

Any changes within the transaction can be administered using the checkout_update event. You need to include the items in an array within this event, which Antavo will then translate into separate checkout_update_item events.

Here’s a standard checkout_update event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,  
SignedHeaders=date;host,  
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
    "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
    "action": "checkout_update",  
    "data": {  
        "transaction_id": "1703545579",  
        "total": 45,  
        "points_burned": 10,  
        "items": [  
            {  
                "product_id": "001",  
                "product_name": "Super Cool T-Shirt",  
                "product_url": "https://www.example.com/products/super-cool-tshirt-001",  
                "price": 50,  
                "quantity": 1,  
                "discount": 5,  
                "subtotal": 45,  
                "points_rewarded": 10  
            }  
        ]  
    }  
}

Checkout accept event

Upon registration of the checkout_accept events, checkout_accept_item events are logged automatically to confirm purchased items.

Here’s a standard checkout_accept event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.us.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "checkout_accept",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Checkout reject event

Only the entire purchase can be rejected. To remove items from the transaction, register a checkout_update event before rejection, without the removed item included in the items array.

Here’s a standard checkout_reject event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.us.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "checkout_reject",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Refunds

Refund event

If the entire purchase is returned, submit a refund event.

Here’s a standard refund event sample. You can find detailed information in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "refund",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Refund_item event

To process a partial refund, you need to submit a refund_item event for each item that has been refunded.

Here’s a standard refund_item event sample. You can find detailed information in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "refund_item",  
  "data": {  
    "transaction_id": "1703545579",  
    "product_id": "001",  
    "quantity": 1,  
      "subtotal: 100"  
  }  
}

Transaction-level transaction lifecycle

If transactions are managed on a transaction level, the submission of item details is not required.

Transaction registration

Here’s a standard checkout event sample if the checkout is administered on the transaction level. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,  
SignedHeaders=date;host,  
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
    "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
    "action": "checkout",  
    "data": {  
        "transaction_id": "1703545579",  
        "total": 150,  
        "points_burned": 10,  
    }  
}

📘

Note

In point-based loyalty schemes, points are assigned based on the total value of the entire purchase.

Pending period

Checkout update event

Any changes within the transaction can be administered using the checkout_update event.

Here’s a standard checkout_update event sample for transaction-level updates. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,  
SignedHeaders=date;host,  
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
    "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
    "action": "checkout_update",  
    "data": {  
        "transaction_id": "1703545579",  
        "total": 100,  
        "points_burned": 10,  
    }  
}

Checkout accept event

To confirm the transaction at the end of the return period, a checkout_accept event has to be sent.

Here’s a standard checkout_accept event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "checkout_accept",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Checkout reject event

Only the entire purchase can be rejected. To reduce the value of the transaction, register a checkout_update event with an updated total value before rejection.

Here’s a standard checkout_reject event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "checkout_reject",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Refunds

Refund event

If the entire purchase is returned, submit a refund event.

Here’s a standard refund event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "refund",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Partial_refund event

To process a partial refund, the refunded amount has to be submitted in the amount event attribute of the partial_refund event.

Here’s a standard partial_refund event sample. You can find detailed information about this event in the API events document.

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "refund_item",  
  "data": {  
    "transaction_id": "1703545579"  
    "amount": 25.00  
  }  
}

Point value of items

In a point-based loyalty scheme, you may want to display the number of points that customers will earn for purchasing certain items in your webstore or offline at the POS. You can use Antavo’s Points preview API endpoint for this purpose.

Points can be queried for single or multiple items, allowing point values to be shown on product pages or the cart page inside the webstore and the interface of the POS. This query is customer-specific, meaning the points are calculated based on the loyalty mechanisms applied to the customer.

Antavo returns both the points assigned for the purchase itself and any additional points granted by Campaign bonus nodes of configured workflows as separate attributes.

You can add only one or multiple items to the request, which should be sent to the Points preview API endpoint. Here’s an example:

{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "checkout",  
  "data": {  
    "transaction_id": "1703545579",  
    "total": 95,  
    "items": [  
      {  
        "product_id": "001",  
        "product_name": "Super Cool T-Shirt",  
        "product_url": "https://www.example.com/products/super-cool-tshirt-001",  
        "price": 50,  
        "quantity": 2,  
        "discount": 5,  
        "subtotal": 95,  
      }  
    ]  
  }  
}

In the response, under campaigns you can see the workflow ID (automation) and the points it grants (bonus). Under purchase, you can see the points awarded for the transaction (base), any bonus points received (bonus), and the sum of both (points).

{  
  "data": {  
    "campaigns": [  
      {  
        "automation": "6679a7fd6348cc7c466f27b4",  
        "points": 15  
      }  
    ],  
    "purchase": {  
      "bonus": 15,  
      "points": 115,  
      "base": 100  
    }  
  }  
}

Using loyalty benefits at checkout

The checkout experience can be extended with Antavo-supported incentives:

• Point burning at checkout
• Coupon redemption
• Offer redemption

Point burning at checkout

In point-based loyalty schemes, customers can spend their accumulated points during checkout to reduce the amount they need to pay.

The monetary value of a point can be configured in the module configuration interface. Additionally, special burn rules can be applied to customer segments within the loyalty program, providing the opportunity for certain customers to receive higher or lower discounts.

🚧

Note

If you send offline transactions to Antavo in bulk outside operational hours, the POS system should disable the functionality to burn points at checkout. This precaution is necessary to prevent fraudulent activities, as offline systems may not have real-time connectivity to the customer’s point balance.

Checking spendable points

If the Burn rules module is enabled, you can check how many points a customer has and their value through the customers/customer_id endpoint of the Customer API. The burn_rates attribute provides this information, which can be used to display on user interfaces during checkout.

Example response snippet showing burn rates:

"burn_rates": [  
        {  
          "amount": 1,
          "points": 50,
          "currency": "GBP",
          "converted_amount": 8,
          "unconverted_points": 40
}

• amount: The currently available amount of discount which can be claimed in exchange for the customer’s points currently available to spend.
• points: The customer’s points currently available to spend.
• currency: The currency of the discount. In the case of different currencies, it is important that the value read from this API matches the currency of the customer’s transaction.
• converted_amount: The total discount in whole currency units (no decimals) that the customer can redeem using their available points.
• unconverted_points: The remaining points after calculating the maximum redeemable amount. These points cannot currently be used for redemption.

Submitting points to be burned

To spend points at checkout, include the points_burned attribute in the checkout event. For item-level transactions, the unit_burn is automatically calculated and registered with the checkout_item event, allowing points to be refunded on an item basis if necessary.

If the customer doesn’t have enough spendable points on their account, the checkout event request will fail with an error and the event will not be registered. This ensures that customers can only spend the points they have earned and prevents negative balances.

📘

Note

When burning points to apply a discount, please remember to calculate the discounted total and subtotal attribute values accurately. Make sure to send the checkout event with these reduced values.

The points_burned value is automatically deducted from the customer’s point balance when the checkout event is registered, even if a pending period is implemented in the transaction lifecycle.

Point restoration on refund

When a refund is processed, any burned points are restored and added back to the customer’s spendable points with the registration of the point_unburn event. This ensures that customers retain their loyalty benefits even in case of returns.

🚧

Note

If a pending period is in effect and the transaction lifecycle ends with a checkout_reject event, the points remain spent and are not returned to the customer's point balance. To address this, a point_unspend event can be submitted to give the points back to the customer.

Coupon redemption

The Coupons module is the interface to manage coupons that can be assigned to customers based on their activities within the loyalty program It allows customers to redeem coupons during checkout and automates the redemption of coupon codes included in the submitted checkout event.

Checking available coupons

To check a customer’s available coupons, use the customers/customer_id/coupons endpoint of the Display API. This endpoint provides detailed information about the coupons a customer can use at checkout. Only coupons with a status of claimed or partially_redeemed are eligible for redemption.

Here’s an example response:

{  
  "data": [  
    {  
      "code": "C24RR562",  
      "status": "claimed",  
      "type": "amount",  
      "value": 5,  
      "currency": "EUR",  
      "created_at": "2024-06-18T08:58:26.605Z",  
      "expires_at": "2024-06-18T08:58:26.605Z",  
      "pool": "EUR 5 COUPONS"  
    }  
  ]  
}

This information can be displayed on user interfaces to inform customers of their available coupons.

Submitting coupon redemption

To redeem a coupon, include the coupons attribute within the checkout event, listing the coupon codes to be used with the purchase. If enabled in the Coupons module, each coupon code included will automatically trigger a separate coupon_redeem event, updating the coupon status to redeemed.

You can also register the coupon_redeem event separately from the checkout event if needed.

For gift card-type coupons, which can be used across multiple transactions until their value is exhausted, automatic redemption via the checkout event is not supported. Make sure you submit the coupon_redeem event separately, including the value redeemed in the amount attribute.

Here’s an example request to submit a coupon_redeem event:

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

{  
   "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
   "action": "coupon_redeem",  
   "data":  {  
       "code": "C24RR562",  
       "transaction_id: "1703545579",  
       "amount": 10  
   }  
}

📘

Note

When applying a coupon to reduce the purchase total, ensure that you calculate and send the adjusted total and subtotal attribute values in the checkout event.

Coupon status change on refund

If a coupon redemption was recorded with the checkout event, a refund will automatically change the coupon status back to claimed with the registration of a coupon_unredeem event, allowing it to be used again.

Also, if all items in the original checkout are refunded individually with refund_item events, the coupon status will also automatically return to claimed and thecoupon_unredeem event is registered.

If the coupon redemption was not done with the checkout event, but separately using the coupon_redeem event, you must also separately submit a coupon_unredeem event during a refund.

Here’s an example request to submit a coupon_unredeem event:

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

{  
   "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
   "action": "coupon_unredeem",  
   "data":  {  
       "code": "C24RR562",  
       "amount": 10  
   }  
}

🚧

Note

If a pending period is in use and the transaction lifecycle ends with a checkout_reject event, the coupon remains redeemed and cannot be reused. To address this, a coupon_unredeem event can be submitted to re-assign the coupon to the customer.

Offer redemption

Antavo’s Offers module provides the functionality to configure incentives that can be applied to customers' shopping carts before an order is submitted. The module supports various types of offers, including product-, or tier-specific discounts and product combination promotions.

Checking available offers

Retrieve available offers for a specific purchase by submitting the content of a customer’s cart through the Offers API:

{  
  "cart": {  
    "total": 25,  
    "discount": 2.2,  
    "shipping": 4.00,  
    "items": [  
      {  
        "product_id": "568433",  
        "quantity": 2,  
        "price": 13.6,  
        "discount": 2.2,  
        "subtotal": 25  
      }  
    ]  
  },  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "store": "3044",  
  "eligible_only": true  
}

For online purchases, display the list of available offers on the cart page. For offline transactions, integrate with the POS interface to allow cashiers to apply the offers on purchases before registering the purchase.

The Offers endpoint of the Display API is also an option to query available offers for the customer, but it does not factor in cart values.

Submitting offer redemption

To redeem an offer, include the offers attribute within the checkout event with the IDs of the offers to be used. Each offer ID included will automatically register an individual offer_redeem event.

📘

Note

When applying an offer to reduce the purchase total, ensure that you calculate and send the adjusted totaland subtotalattribute values in the checkoutevent.

Cancel offer redemption on refund

During the refund, include the IDs of used offers in the offers attribute to trigger an offer_unredeem event. Unlike in the case of coupons, the offer_unredeem event doesn’t have to be sent separately, it is automatically registered if the attribute is present in the event.

Here’s an example request to submit a refund event with an offer to be unredeemed:

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

{  
   "customer": "d6e0e99-3a92-4285-ad74-97c2e7783fe0",  
   "action": "refund",  
   "data":  {  
       "transaction_id": "1703545579"  
       "offers": ["63e95c4d0c12a2615822e913"]  
   }  
}

Alternatively, you can also submit this event separately from the refund event.

Here’s an example request to submit an offer_unredeem event:

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

{  
   "customer": "d6e0e99-3a92-4285-ad74-97c2e7783fe0",  
   "action": "offer_unredeem",  
   "data":  {  
       "offer": "63e95c4d0c12a2615822e913"  
   }
}

Accessing transactional data

To access transaction-related events, follow the guidelines in the Actions and Events documentation.

You can filter for specific events by adding parameters to your requests. For example: customers/{customer_id}/events?action=checkout.

Beyond querying events, you have two methods to access transaction data:

• Management UI: You can review individual customer’s transaction history by opening their profile in the Management UI and navigating to the Transactions tab.
• Display API: The Transactions endpoints of the Display API allow you to access an individual customer’s transactions via an API request.
  This method is ideal for integrating transaction data directly into your systems and applications with on-demand querying. However, for large-scale data queries, it is recommended not to submit them through this API endpoint. Instead, webhook messages should be sent to a downstream system for storage and processing purposes.

Draft transactions

Draft transactions provide a way to track and manage incomplete transactions until all necessary data is available.

A draft transaction is created whenever you submit any event with a unique transaction_id, except for the checkout event. This initial submission results in an incomplete transaction record, marked as draft. To finalize and process this transaction, you need to submit a valid checkout event with the same transaction_id. This moves the draft transaction into a regular transaction, initiating its normal lifecycle.

When you query a draft transaction using the /customers/{customer_id}/transactions/{transaction_id} endpoint of the Display API, you will receive a response similar to the following:

{  
   "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

Antavo’s Customer ID validation module offers a seamless way to handle guest checkouts, enabling transactions to be later claimed by active members of the loyalty program.

Submitting a guest checkout event

To submit a guest checkout event, use a standard checkout event, but replace the customer attribute with the guest attribute set to true. This approach allows the transaction to be recorded without associating it with a specific customer initially.

Here’s an example of a guest checkout event:

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
 "action": "checkout",  
 "guest": "true",  
 "data": {  
     "transaction_id": "1703545579",  
     "total": 95,  
     "items": [  
         {  
             "product_id": "001",  
              "product_name": "Super Cool T-Shirt",  
              "product_url": "https://www.example.com/products/super-cool-tshirt-001",  
              "price": 50,  
              "quantity": 2,  
              "discount": 5,  
              "subtotal": 95,  
              "points_rewarded": 20  
         }  
     ]  
 }  
 }

Claiming a guest checkout

Once a guest checkout is registered, it can be claimed by an active member using the checkout_claim API event. The transaction will then be added to the transaction history of the customer specified in the customer attribute. For more detailed information, refer to the API events document.

Here’s an example of a checkout_claim event:

POST /events  
Host: api.{environment}.antavo.com  
Authorization: ANTAVO-HMAC-SHA256 Credential=YOUR_API_KEY/20240615/us/api/antavo_request, SignedHeaders=date;host, Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc  
{  
  "customer": "dd6e0e99-3a92-4285-ad74-97c2e7783fe0",  
  "action": "checkout_claim",  
  "data": {  
    "transaction_id": "1703545579"  
  }  
}

Product and Store management

Product catalog

The Product catalog module enables the correlation of purchased items with a detailed list of all products.
By submitting the Product ID in a checkout-related event, Antavo can automatically identify the product and register the corresponding information based on the product database, reducing the size and complexity of transaction-related event submission.

Methods of adding new products:

• Manually through the Products module configuration interface
• Using the Imports module
• Submitting a request to the /entities/products/product/{product_id} Entities API endpoint.

📘

Note

The list of products can be retrieved by submitting a GET request to the /entities/products/product Entities API endpoint or exported through the Exports module.

Stores

The Stores module adds the store attribute to the checkout event, which can be used to track the location of purchases and enables the use of store-specific benefits and campaigns.

Methods of adding new products:

• Manually through the Stores module configuration interface
• Using the Imports module
• Submitting a request to the /entities/stores/store/{store_id} Entities API endpoint.

📘

Note

The list of products can be retrieved by submitting a request to the /entities/stores/store Entities API endpoint or exported through the Exports module.

Workflows

The built-in functionalities of the mentioned modules can be expanded and overwritten by configuring custom rules in the Workflows editor. For a comprehensive guide on using workflows, please refer to this user manual.

Some of the use cases include:

• Modifying the number of points rewarded based on customer tier or customer segments.
• Registering transaction details in customer attributes.
• Triggering email communication of the earned benefits.