API events

challenge_reset

Minimal Buttons

Submitting this event triggers a reset of the specified challenge's progress count, setting the current value of completed criteria to 0. Challenges, whether partially or fully completed, can undergo this reset process, provided the resettable flag is enabled in the Antavo Management UI.

Attribute	Description	Required	Type
challenge	The unique ID of the challenge to be reset.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "challenge_reset",
   "data":  {
       "challenge": "63eaabe8b0fe6815c91425b6"
   }

}

checkout

The submission of this event records a customer’s purchase.

If a checkout confirmation logic is configured within the Checkout accept module, an additional step is necessary to confirm or reject the transaction, thereby determining point allocation.

Attribute	Description	Required	Type
transaction_id	Serves as a unique identifier for each transaction. Submitting an event with a pre-existing transaction_id will result in rejection as a duplicate, accompanied by the ERR_TX_ALREADY_EXISTS error message.	yes	string
total	The total amount paid in the transaction.	yes - if purchases are rewarded on the transaction level no - if purchases are rewarded on the item level	numeric
items	A list of line items detailing the products or services purchased, each with specific attributes. The `checkout_item` event captures these details, including all characteristics associated with the purchased items.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	list
points_burned	The amount of loyalty points used by customers in the transaction. Upon successful submission, Antavo reserves points if a pending mechanism is applied. Transactions exceeding the customer’s spendable points will be rejected. Transactions may show a negative points value due to this attribute. For approval, the total available points for the customer to spend, including any points reserved for this transaction, must be sufficient.	no	numeric
channel	Represents the platform or medium where a transaction or interaction occurs, such as "store," "mobile," "online," or specific channels like "POS" (Point of Sale) or "API".	no	string
currency	The three-character ISO 4217 currency code used for the transaction, such as USD, EUR, or GBP.	no	select
country	The three-character ISO 3166 country code representing the country of the transaction, such as USA, FRA, or GBR.	no	string
discount	The amount of discount applied to the purchase. Submitting this information might be useful for scenarios where transactions are rewarded for full-price purchases only.	no	numeric
shipping	The cost of shipping. Based on this information bonus points or other benefits can be awarded to customers.	no	numeric
points_rewarded	A positive integer representing the number of points awarded for the entire purchase, overriding default calculations if specified.	no	numeric
total_quantity	The total number of items in the transaction.	no	numeric
auto_accept	The default auto-accept date is calculated by the Checkout accept module. Allows overriding the default auto-accept date with a specified date. Use `null` or an empty string to require manual acceptance or rejection._ Requires the Checkout accept module to be enabled in the workspace.	no	date
coupon_code DEPRECATED_	A coupon code automatically redeemed upon successful `checkout` event submission. Requires the Coupons module to be enabled in the workspace.	no	string
coupons	An array of coupon codes automatically redeemed upon a successful `checkout` event submission. Requires the Coupons module to be enabled in the workspace.	no	list
offers	An array of offers associated with the transaction. Requires the Offers module to be enabled in the workspace.	no	list
club_id	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	no	string
club_points	The total number of points added to the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "checkout",
   "data":  {
       "transaction_id": "TR37882412",
       "total": 100,
       "total_quantity": 2,
       "currency": "EUR",
       "points_burned": 0,
       "items": [
            {
               "product_id": "prd_987654",
               "product_name": "Vintage Leather Jacket",
               "product_url": "https://example.com/products/vintage-leather-jacket",
               "price": 50,
               "quantity": 1,
               "discount": 0,
               "subtotal": 50,
               "points_rewarded": 0
           			},
             {
               "product_id": "prd_123456",
               "product_name": "Classic Denim Jeans",
               "product_url": "https://example.com/products/classic-denim-jeans",
               "price": 50,
               "quantity": 1,
               "discount": 0,
               "subtotal": 50,
               "points_rewarded": 0
              	}
       ]
   }

}

checkout_item

This event defines line items within a purchase, providing detailed information about the purchased product (e.g. name, product category, SKU, quantity, and price). Checkout_item events are created from items sent within a checkout event. The checkout_item inherits all attributes from the checkout event, provided the attribute names are the same.

Although a checkout_item event can be submitted independently without a checkout event, it is not recommended as point calculation will not occur in this case. It's strongly recommended that the subtotal attribute is externally calculated using the formula: (price - discount) x quantity = subtotal.

Attribute	Description	Required	Type
transaction_id	Serves as a unique identifier for each transaction.	yes	string
total	The total amount paid in the transaction.	yes - if purchases are rewarded on the transaction level no - if purchases are rewarded on the item level	numeric
product_id	A unique identifier associated with the product, matching the product ID values in all non-Antavo systems.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	string
product_name	The name of the item as recognized in external systems.	no	string
product_url	The web address leading to the product’s online store page.	no	string
product_category	The categories or subcategories that the product falls under.	no	string
quantity	The number of items purchased during the transaction.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	numeric
currency	The three-character ISO 4217 currency code used for the transaction, such as USD, EUR, or GBP.	no	select
country	The three-character ISO 3166 country code representing the country of the transaction, such as USA, FRA, or GBR.	no	string
discount	The amount of discount applied to the item. Submitting this information might be useful for scenarios where transactions are rewarded for full-price purchases only.	no	numeric
points_rewarded	A positive integer representing the number of points awarded for the entire purchase, overriding default calculations if specified.	no	numeric
total_quantity	The total number of items in the transaction.	no	numeric
auto_accept	The default auto-accept date is calculated by the Checkout accept module. Allows overriding the default auto-accept date with a specified date. Use `null` or an empty string to require manual acceptance or rejection. Requires the Checkout accept module to be enabled in the workspace.	no	date
subtotal	The amount paid per item.	yes	numeric
price	The full value of a single item before any discounts. This value must be entered manually as it is not calculated automatically by Antavo.	yes	numeric
unit_burn	Logs how loyalty points burned on a transaction are divided among individual items, allowing for accurate point adjustments if a refund is issued for any items.	no	numeric
club_id	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	no	string
club_points	The total number of points added to the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	no	numeric

checkout_update

Minimal Buttons

This event updates information in a pending checkout before approval, using checkout_update_item events. It's the only way to remove items from a pending checkout.

Attribute	Description	Required	Type
total	The total amount paid to be updated in the transaction.	yes - if purchases are rewarded on the transaction level no - if purchases are rewarded on the item level	numeric
transacion_id	Unique identifier of the pending checkout to be modified.	yes	string
items	A list of line items detailing the products or services purchased, each with specific attributes. The `checkout_update_item` event captures these details, including all characteristics associated with the purchased items.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	list
points_burned	The amount of loyalty points used by customers in the transaction. Upon successful submission, Antavo reserves points if a pending mechanism is applied. Transactions exceeding the customer’s spendable points will be rejected. Transactions may show a negative points value due to this attribute. For approval, the total available points for the customer to spend, including any points reserved for this transaction, must be sufficient.	no	numeric
points_rewarded	A positive integer representing the number of points awarded for the entire purchase, overriding default calculations if specified.	no	numeric
total_quantity	The total number of items in the transaction.	no	numeric
channel	Represents the platform or medium where a transaction or interaction occurs, such as "store," "mobile," "online," or specific channels like "POS" (Point of Sale) or "API".	no	string
currency	The three-character ISO 4217 currency code used for the transaction, such as USD, EUR, or GBP.	vo	select
country	The three-character ISO 3166 country code representing the country of the transaction, such as USA, FRA, or GBR.	no	string
discount	The amount of discount applied to the purchase. Submitting this information might be useful for scenarios where transactions are rewarded for full-price purchases only.	no	numeric
shipping	The cost of shipping. Based on this information bonus points or other benefits can be awarded to customers.	no	numeric
auto-accept	The default auto-accept date is calculated by the Checkout accept module. Allows overriding the default auto-accept date with a specified date. Use `null` or an empty string to require manual acceptance or rejection. Requires the Checkout accept module to be enabled in the workspace.	no	date

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "checkout_update",
   "data":  {
       "transaction_id": "TR37882412",
       "total": 100,
     	 "total_quantity": 3,
       "currency": "EUR",
       "points_burned": 0,
       "items": [
           {
              "product_id": "prd_987654",
              "product_name": "Vintage Leather Jacket",
              "product_url": "https://example.com/products/vintage-leather-jacket",
              "price": 50,
              "quantity": 2,
              "discount": 0,
              "subtotal": 100,
              "points_rewarded": 0
            	},
            {
              "product_id": "prd_123456",
              "product_name": "Classic Denim Jeans",
              "product_url": "https://example.com/products/classic-denim-jeans",
              "price": 50,
              "quantity": 1,
              "discount": 0,
              "subtotal": 50,
              "points_rewarded": 0
             	}
       ]
   }

}

checkout_update_item

Minimal Buttons

This event updates line items for purchases, providing detailed information such as product name, category, SKU, quantity, and price. The checkout_update_item inherits all attributes from the checkout_update event, provided the attribute names are the same.

Although a checkout_update_item event can be submitted independently without a checkout_update event, it is not recommended as point calculation will not occur in this case.

Attribute	Description	Required	Type
transaction_id	Unique identifier of the pending checkout to be modified.	yes	string
total	The total amount paid to be updated in the transaction.	no	numeric
product_id	A unique identifier associated with the product, matching the product ID values in all non-Antavo systems.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	string
product_name	The name of the item as recognized in external systems.	no	string
product_url	The web address leading to the product’s online store page.	no	string
quantity	The number of items purchased during the transaction.	no	numeric
country	The three-character ISO 3166 country code representing the country of the transaction, such as USA, FRA, or GBR.	no	string
points_rewarded	A positive integer representing the number of points awarded for the entire purchase, overriding default calculations if specified.	no	numeric
subtotal	The amount paid per item.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	numeric
price	The full value of a single item before any discounts. This value must be entered manually as it is not calculated automatically by Antavo.	no	numeric
discount	The amount of discount applied to the item. Submitting this information might be useful for scenarios where transactions are rewarded for full-price purchases only.	no	numeric
unit_burn	Logs how loyalty points burned on a transaction are divided among individual items, allowing for accurate point adjustments if a refund is issued for any items.	no	numeric
currency	The three-character ISO 4217 currency code used for the transaction, such as USD, EUR, or GBP.	no	string
total_quantity	The total number of items in the transaction.	no	numeric

checkout_accept

Minimal Buttons

The submission of this event initiates checkout confirmation. The approval process of pending checkouts involves using a standard checkoutevent.

Please note that this event cannot modify checkout data. To modify transactions, use the checkout_updateevent.

Attribute	Description	Required	Type
transaction_id	Unique identifier of the pending checkout to be accepted.	yes	string
total	The total amount paid in the transaction.	yes	numeric
currency	The three-character ISO 4217 currency code used for the transaction, such as USD, EUR, or GBP.	no	select
shipping_country	The country to which the shipping is being made.	no	string
total_quantity	The total number of items in the transaction.	no	numeric
checkout_date	The date when the transaction occurred.	no	string
points_rewarded	A positive integer representing the number of points awarded for the entire purchase, overriding default calculations if specified.	no	numeric
club_id	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	no	string
club_points	The total number of points added to the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "checkout_accept",
   "data":  {
       "transaction_id": "TR37882412"
   }

}

checkout_accept_item

Minimal Buttons

This event accepts line items for purchases, providing detailed information about the product name, category, SKU, quantity, and price.

All information within this event originates from the corresponding checkout_item and checkout_update_item events. It cannot be directly submitted but is created from a checkout_accept event.

Attribute	Description	Required	Type
transaction_id	Unique identifier of the pending checkout to be accepted.	yes	string
total	The total amount paid in the transaction.	yes - if purchases are rewarded on the transaction level no - if purchases are rewarded on the item level	numeric
product_id	A unique identifier associated with the product, matching the product ID values in all non-Antavo systems.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	string
product_name	The name of the item as recognized in external systems.	no	string
product_url	The web address leading to the product’s online store page.	no	string
quantity	The number of items purchased during the transaction.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	numeric
country	The three-character ISO 3166 country code representing the country of the transaction, such as USA, FRA, or GBR.	no	string
points_rewarded	A positive integer representing the number of points awarded for the entire purchase, overriding default calculations if specified.	no	numeric
subtotal	The amount paid per item.	yes - if purchases are rewarded on the item level no - if purchases are rewarded on the transaction level	numeric
price	The full value of a single item before any discounts. This value must be entered manually as it is not calculated automatically by Antavo.	no	numeric
discount	The amount of discount applied to the item. Submitting this information might be useful for scenarios where transactions are rewarded for full-price purchases only.	no	numeric
unit_burn	Logs how loyalty points burned on a transaction are divided among individual items, allowing for accurate point adjustments if a refund is issued for any items.	no	numeric
currency	The three-character ISO 4217 currency code used for the transaction, such as USD, EUR, or GBP.	no	string
checkout_date	The date when the transaction occurred.	no	string
club_id	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	no	string
club_points	The total number of points added to the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	no	numeric

checkout_reject

Minimal Buttons

The submission of this event records the rejection of pending checkouts.

Attribute	Description	Required	Type
transaction_id	Unique identifier of the pending checkout to be rejected.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "checkout_reject",
   "data":  {
       "transaction_id": "TR37882412"
   }

}

checkout_claim

Minimal Buttons

When this event is submitted, it adds a previously registered guest checkout to the customer’s transaction history. This event links the guest transaction with the submitted transaction_id.

Attribute	Description	Required	Type
transaction_id	A unique transaction ID of a submitted guest checkout.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "checkout_claim",
   "data":  {
       "transaction_id": "TR37882412"
   }

}

coupon

Deprecated

This event generates a coupon with a specified code and assigns it to a customer. If you want to associate the generated coupon with a predefined coupon pool, use the coupon_create event instead.

Attribute	Description	Required	Type
code	The coupon code to be generated.	yes	string
amount	The value of the coupon expressed either as a monetary amount or as a percentage discount.	no	numeric
expiration_date	The expiration date of the coupon.	no	string

coupon_create

Minimal Buttons

This event triggers the generation of a coupon for a customer, automatically assigning it to them.

Attribute	Description	Required	Type
code	The coupon code to be generated.	yes	string
name	The name of the coupon.	no	string
currency	The three-character ISO 4217 currency code used for the coupon, such as USD, EUR, or GBP.	no	string
value	The value of the coupon expressed either as a monetary amount or as a percentage discount.	yes	numeric
type	The type of the coupon: amount, percentage, gift card, or free shipping.	no	select
expdate	The expiration date of the coupon.	no	string
pool	The corresponding coupon pool.	no	string
stores	Store identifiers where the coupon will be applicable.	no	list
products	Product identifiers to which the coupon will apply.	no	list
cost	The associated business cost of the coupon.	no	numeric

POST /events
Host: api.>environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=API_KEY/20181207/demo/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "coupon_create",
   "data":  {
       "code": "TC22341",
       "name": "20% coupon",
       "currency": "GBP",
       "type": "amount",
       "value": 20
   }

}

coupon_invalidate

Minimal Buttons

This event invalidates the specified coupon code.

Attribute	Description	Required	Type
code	The code of the coupon to be invalidated.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "coupon_invalidate",
   "data":  {
       "code": "TC22341"
   }

}

coupon_redeem

Minimal Buttons

This event records the redemption of a coupon, using the timestamp of the event.

Coupons can be automatically redeemed if enabled in the module settings.

Attribute	Description	Required	Type
code	The coupon code to be redeemed.	yes	string
transaction_id	The unique ID of the transaction where the coupon was applied.	no	string
amount	The value of the coupon, required only for multiple-use gift card coupons. It ranges from 0 up to the total available in the coupon’s balance field.	no	numeric
cost	The associated business cost of the coupon.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "coupon_redeem",
   "data":  {
       "code": "TC22341"
   }

}

coupon_unredeem

Minimal Buttons

This event resets a coupon to an unredeemed state.

Attribute	Description	Required	Type
code	The code of the coupon to be reset to an unredeemed state.	yes	string
amount	The value of the coupon expressed either as a monetary amount or as a percentage discount.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "coupon_unredeem",
   "data":  {
       "code": "TC22341"
   }

}

coupon_transfer

Minimal Buttons

This event transfers a claimed coupon reward from one customer to another. It can only be triggered for coupon rewards where the Transferable flag is enabled in the Management UI reward configuration interface.

Attribute	Description	Required	Type
code	The coupon code to be transferred.	yes	string
email	The email address of the recipient customer. If the provided email does not match an existing customer, an inactive customer profile will be created.	no	string
target	The unique ID of the customer to whom the coupon is being transferred.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "coupon_transfer",
   "data":  {
       "code": "TC22341",
       "email": "[email protected]" ,
       "target": "280e674c-de2a-4a30-987a-d9267d1a1194",
   }

}

coupon_unassign

Minimal Buttons

The event registers the unassignment of a coupon from the customer.

Attribute	Description	Required	Type
code	The code of the coupon to be unassigned.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "coupon_unassign",
   "data":  {
       "code": "TC22341"
   }

}

customer_list_customer_add

This event is registered when a customer is added to a specific customer list, It captures the action of adding a customer to a list, which can occur through an API event submission, manual addition via the Management UI, or triggered by a workflow.

Attribute	Description	Required	Type
customer_list_id	The ID of the list the customer should be added to.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "customer_list_customer_add",
   "data":  {
       "customer_list_id": "63f2cc942d6ef241c0167e6c"
   }

}

customer_list_customer_remove

This event is registered when a customer is removed from a specific customer list. It captures the action of removing a customer from a list, which can occur through an API event submission, manual removal via the Management UI, or triggered by a workflow.

Attribute	Description	Required	Type
customer_list_id	The ID of the list the customer should be removed from.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "customer_list_remove",
   "data":  {
       "customer_list_id": "63f2cc942d6ef241c0167e6c"
   }

}

daily_login

This event is recorded when a customer authenticates as a member of the loyalty program. It is logged only once per day.

This event automatically updates the customers.last_login_at attribute, allowing access to the customer's most recent login date information as a data attribute.

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "daily_login"
}

modify_purchase_total

This event enables adjustment of the customer's purchase total by either increasing or decreasing the amount.

Attribute	Description	Required	Type
amount	Specifies the total amount by which the customer's purchase total should be adjusted	yes	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "modify_purchase_total",
   "data":  {
       "amount": "1132"
   }

}

newsletter_click

Minimal Buttons

This event is registered when a customer clicks a link embedded within a newsletter, which includes a tracking code.

Attribute	Description	Required	Type
campaign	The unique ID associated with the newsletter.	yes	string
url	The URL containing the tracking code.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "newsletter_click",
   "data":  {
       "campaign": "63f2cc942",
     	 "url": "https://example.com/summer-campaign-24
   }

}

offer_unredeem

Minimal Buttons

This event is submitted to revert a previously redeemed offer to an unredeemed state.

Attribute	Description	Required	Type
offer	The unique ID of the offer	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "offer_unredeem",
   "data":  {
       "offer": "62c7f2865fcba349400fe78b"
   }

}

offline_treasure_code_found

Minimal Buttons

This event is submitted to record that a customer has found an offline treasure code with the code included.

Attribute	Description	Required	Type
treasure_id	The ID of the treasure.	yes	string
code	The reasure code.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "offline_treasure_code_found",
   "data":  {
       "treasure_id": "6331aeac7977870c8576e912",
   }

}

offline_treasure_found

Minimal Buttons

This event is submitted to record that a customer has found an offline treasure code.

Attribute	Description	Required	Type
treasure_id	The ID of the treasure.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "offline_treasure_found",
   "data":  {
       "treasure_id": "6331aeac7977870c8576e912",
   }

}

treasure_found

Minimal Buttons

This event records when a customer discovers an online treasure.

Attribute	Description	Required	Type
treasure_id	The ID of the treasure.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "treasure_found",
   "data":  {
       "treasure_id": "64f71fa2a0d80d2eb43fb66a",
   }

}

opt_in

This event enrolls a customer in the loyalty program, serving as the initial recorded event for new customers in Antavo. It also registers the unique identifier for the newly created customer.

Please note that certain attributes of this event are automatically included upon activation of the Shopify module.

Attribute	Description	Required	Type
email	The customer's valid email address.	yes	string
first_name	The customer's first name.	no	string
last_name	The customer's last name	no	string
handler	The nickname displayed on the customer's profile.	no	string
language	An ISO 639-2 code identifying the customer's language. While any value is accepted, recognized language codes may display loyalty pages in the user’s language, if available.	no	string
currency	An ISO 4217 currency code identifying the customer's currency (such as USD (U.S. Dollar), EUR (Euro), or GBP (British Pound).	no	select
birth_date	The customer's birth date in YYYY-MM-DD format. Invalid entries will result in event submission rejection.	no	date
referrer	The unique account ID of the customer who referred the new member to the loyalty program. Requires the Friend referral module to be enabled in the workspace.	no	string
mobile_phone	The customer's mobile phone number.	no	string
source	The origin of registration, indicating where it was initiated (e.g., website, mobile app, store).	no	string
membership_id	A unique identifier for membership, used across platforms including mobile apps. This ID may function as a range of IDs in specific contexts.	no	list
labels	Allows external segmentation by assigning specific tags to customers.	no	list
country	The country where the customer is located.	no	select
gender	The gender of the customer.	no	select

POST /events
Host: api.>environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=API_KEY/20181207/demp/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "opt_in",
   "data":  {
       "email": "[email protected]",
       "first_name": "Sally",
       "last_name": "Thompson",
       "handler": "Sally",
       "referrer": "280e674c-de2a-4a30-987a-d9267d1a119",
     	 "source": "website",
     	 "currency": "EUR",
     	 "language": "en"
   }

}

opt_out

This event unenrolls a customer from the loyalty program.

The opt-out process adheres to GDPR regulations. All identifiable customer information is hashed, rendering it non-recoverable. Transaction-related data is retained, but the customer remains anonymous.

Attribute	Description	Required	Type
reason	The reason why the customer leaves the loyalty program.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "opt_out",
   "data":  {
       "reason": "deleted webstore account"
   }

}

pending_invalidate

Minimal Buttons

This event invalidates the specified pending event managed by the Pending events module.

Attribute	Description	Required	Type
event	The ID of the pending event to be invalidated.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "pending_invalidate",
   "data":  {
       "event": "6679a6b9be071308dc234b22"
   }

}

pending_validate

Minimal Buttons

This event validates the specified pending event managed by the Pending events module.

Attribute	Description	Required	Type
event	The ID of the pending event to be validated.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "pending_validate",
   "data":  {
       "event": "6679a6b9be071308dc234b22"
   }

}

point_add

This event increases the customer’s point balance by adding points, contributing to the customer’s overall accumulation of loyalty points (earned/score).

Users in the Management UI can use this event to manually correct a customer’s point balance in case of discrepancies.

Attribute	Description	Required	Type
points	Specifies a positive number of points to be added to the customer’s overall score.	yes	numeric
reason	The reason for the point fix.	no	string
transaction_id	The unique ID transaction associated with the point addition.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "point_add",
   "data":  {
       "points": 100,
       "reason": "complimentary points"
   }

}

point_fix

This event allows for adjusting the number of earned points or score points. The specified point value is added to the score. A negative value can be submitted to deduct points from the spendable points.

Attribute	Description	Required	Type
points	Specifies the number of points to be adjusted. Positive values increase the score, while negative values decrease the number of spent points.	yes	numeric
reason	The reason for the point fix.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "point_fix",
   "data":  {
       "points": 100,
       "reason": "shipping issues"
   }

}

point_spend

This event adjusts the customer’s point balance by subtracting points. It increases the number of spent/burned points, simulating the redemption of points at checkout or for a reward. This action does not affect the customer’s all-time collected points (earned/score).

Management UI users can also use this event to manually adjust the customer’s point balance.

Attribute	Description	Required	Type
points	Specifies the number of points to be spent. Only positive integers are accepted.	yes	numeric
reason	The reason for the point spend.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "point_spend",
   "data":  {
       "points": 100,
       "reason": "The customer has problems burning points."
   }

}

point_sub

This event adjusts the customer’s point balance by deducting points. It decreases the customer’s all-time collected points (score) and consequently reduces the number of spendable points.

Management UI users can also use this event to correct a customer’s score in case of misalignment manually.

Attribute	Description	Required	Type
points	he number of points to deduct from the customer’s score. Only positive integers are accepted for this operation.	yes	numeric
reason	The reason for the point deduction.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "point_sub",
   "data":  {
       "points": 100,
       "reason": "segmentation problems"
   }

}

point_unspend

This event adjusts the customer’s point balance by adding spendable points back to their account. This action does not impact the customer’s all-time collected points (score), but reduces the number of spent/burned points, simulating scenarios such as point refunds or reward claim reversals.

Management UI users can also use this event to manually adjust the customer’s point balance.

Attribute	Description	Required	Type
points	A positive integer representing the number of points to be added to the customer's balance.	yes	numeric
reason	The reason for adding spendable points.	no	string
transaction_id	The unique ID transaction associated with the point addition.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "point_unspend",
   "data":  {
       "points": 100,
       "reason": "customer returned a reward to store_london_02"
   }

}

profile

This event is used to update customer attribute data.

Attribute	Description	Required	Type
opt_in	If set to true, this event creates a customer profile with the submitted attributes.	no	boolean
email	The customer's valid email address.	no	string
first_name	The customer's first name.	no	string
last_name	The customer's last name	no	string
handler	The nickname displayed on the customer's profile.	no	string
gender	The gender of the customer.	no	select
birth_date	The customer's birth date in YYYY-MM-DD format. Invalid entries will result in event submission rejection.	no	date
image_url	The web address of the customer’s profile picture.	no	string
facebook_id	The customer’s Facebook profile ID.	no	string
language	An ISO 639-2 code identifying the customer's language. While any value is accepted, recognized language codes may display loyalty pages in the user’s language, if available.	no	string
currency	An ISO 4217 currency code identifying the customer's currency (such as USD (U.S. Dollar), EUR (Euro), or GBP (British Pound).	no	select
membership_id	A unique identifier for membership, used across platforms including mobile apps. This ID may function as a range of IDs in specific contexts.	no	list
mobile_phone	The customer's mobile phone number.	no	string
country	The country where the customer is located.	no	select
labels	Allows external segmentation by assigning specific tags to customers.	no	list

POST /events
Host: api.environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=API_KEY/20181207/demo/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "profile",
   "data":  {
       "email": "[email protected]",
       "first_name": "Sally",
       "last_name": "Thompson",
     	 "birth_date": "1992-12-21",
       "labels": [
                       "vip_customer",
                       "london-returning"
       ]
   }

}

partial_refund

The submission of this event registers when a part of a customer purchase is refunded in a loyalty program where points are rewarded on the transaction level. It facilitates refunding a specified amount, typically less than the full transaction amount. Upon successful submission of this event:

The specified amount is deducted from all transaction details.
The customer's score is reduced, without altering the customer’s number of spent points.
Burned points are restored using the point_unburn event.
The transaction's point earn and burn attributes are updated.
The customer's expiring points (set by the Expiring points) are updated.

If a checkout confirmation logic is configured within the Checkout accept, only transactions with an accepted status can be refunded.

Attribute	Description	Required	Type
transaction_id	This unique ID is used to identify the refunded transaction.	yes	string
amount	The monetary value that has been refunded	yes	numeric
exhausted	Indicates if the entire purchase has been refunded or not.	no	boolean
club_id	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	no	string
club_refunded_points	The total number of points from the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "partial_refund",
   "data":  {
       "transaction_id": "TR37882412",
       "amount": 140,
     	 "exhausted": false
   }

}

refund_item

This event allows for itemized refunds to be processed for customers in a loyalty program where points are rewarded on the item level.

Points earned from the associated item purchase will be deducted.
Burnt points will be restored as spendable points to the customer.

This action should not be used with a pending checkout. Note that this event does not update or change the total attribute of the transaction or transaction items.

🚧
Note
If point expiration is configured, the event deducts points from checkouts in First-Come-First-Served method. This means that points are deducted starting from the earliest available points, not necessarily from the transaction defined by the transaction_id attribute.

Attribute	Required	Description	Type
transaction_id	yes	This unique ID is used to identify the refunded transaction.	string
product_id	yes	A unique identifier linked to the refunded product. This ID must match the product ID values used in all non-Antavo systems.	string
quantity	yes	The number of items purchased during the transaction that are being refunded.	numeric
subtotal	no	The amount paid per item that is being refunded.	numeric
club_id	no	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	string
club_refunded_points	no	The total number of points from the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "refund_item",
   "data":  {
       "transaction_id": "TR37882412",
       "product_id": "prd_987654",
       "quantity": 2,
     	 "subtotal": 100
   }

}

refund

This event registers the refund of all items within a purchase, resulting in the removal of any points earned by the customer.

Attribute	Description	Required	Type
transaction_id	This unique ID is used to identify the refunded transaction.	yes	string
offers	An array of offers that are associated with the refund.	no	list
club_id	The ID of the club associated with this transaction. Requires the Clubs module to be enabled in the workspace.	no	string
club_refunded_points	The total number of points from the club’s point balance as a result of the transaction. Requires the Clubs module to be enabled in the workspace.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "refund",
   "data":  {
       "transaction_id": "TR37882412"
   }

}

release_points

This event releases points that were previously reserved.

Attribute	Description	Required	Type
transaction_id	This unique ID is used to identify the transaction.	yes	string
points	The number of points to be released.	no	numeric

POST /events
Host: api.environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=API_KEY/20181207/demo/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "release_points",
   "data":  {
       "transaction_id": "TR37882412",
       "points": 250
   }

}

reserve_points

The submission of this event results in points being reserved.

Attribute	Description	Required	Type
transaction_id	This unique ID is used to identify the transaction.	yes	string
points	The number of points to be reversed.	yes	numeric

POST /events
Host: api.environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=API_KEY/20181207/demo/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "reserve_points",
   "data":  {
       "transaction_id": "TR37882412",
       "points": 150
   }

}

review_submit

Minimal Buttons

Submitting this event records that a customer has submitted a review.

Attribute	Description	Required	Type
item	The unique product ID of the item being reviewed.	yes	string
review	The text content of the review.	yes	string
provider	The name of the reviewer who submitted the review.	no	string
review_id	The unique identifier assigned to the review submission.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "review_submit",
   "data":  {
       "item": "prd_987654",
       "review": "I absolutely love my new jacket! The leather is incredibly soft and feels very high-quality.",
       "provider": "Sally Thompson",
       "review_id": "445e332"
   }

}

share (legacy)

Minimal Buttons

Attribute	Description	Required	Type
network	The platform where the page was shared.	yes	string
url	The web address of the page that was shared.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "share",
   "data":  {
       "network": "facebook",
       "url": "https://example.com/products/vintage-leather-jacket"
   }

}

share_impression (legacy)

Minimal Buttons

The submission of this registers a customer clicking through a link previously shared using the mechanism provided by the Social share module.

Attribute	Description	Required	Type
url	The web address of the page that was shared.	yes	string
referrer	The ID of the customer who shared the page.	no	string
visitor	The ID of the customer who clicked on the shared link (referee).	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "share_impression",
   "data":  {
       "url": "https://example.com/summer_welcome_promotion",
       "visitor": "280e674c-de2a-4a30-987a-d9267d1a119"
   }

}

This event creates an inactive customer profile in Antavo. Unlike opt_in, subscribing does not enroll the customer as an active member of the loyalty program.

Attribute	Description	Required	Type
email	The email address of the customer.	no	string
first_name	The customer's first name.	no	string
last_name	The customer's last name.	no	string
handler	The nickname displayed on the customer's profile.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "subscribe",
   "data":  {
     "email": "[email protected]",
     "first_name": "Sally",
     "last_name": "Thompson",
     "handler": "Sally"
   }

}

suspend

This event changes the status of an active customer to suspended, preventing them from spending points.

Attribute	Description	Required	Type
reason	The reason for suspending the customer's account.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "suspend",
   "data":  {
       "reason": "potential fraud - under investigation"
   }

}

unsuspend

This event reverses the effect of the suspend event, restoring the status of a suspended customer to active, thereby allowing them to resume spending points.

Attribute	Description	Required	Type
reason	The reason for unsuspending the customer's account.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "unsuspend",
   "data":  {
       "reason": "customer's behavior is not fraudulent"
   }

}

verify_customer

Minimal Buttons

This event registers when a customer verifies their enrollment in the loyalty program by clicking a verification link sent to their email address. Until verification, the customer remains in pending status.

video

This event logs when a customer watches a video.

Attribute	Description	Required	Type
network	The platform on which the video was viewed.	no	string
video_id	The unique ID of the video.	no	string
url	The referring web address of the video. It must be a complete and valid URL.	no	string
title	The title of the video.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "video",
   "data":  {
      "network": "https://www.youtube.com/",
       "video_id": "ViVJPjInPxg",
       "url": "https://www.youtube.com/watch?v=v123456789",
       "title": "How to Style a Vintage Leather Jacket"
   }

}

visit

This event logs when a customer visits a webpage.

Attribute	Description	Required	Type
url	The web address of the visited website. It must be a complete and valid URL.	yes	string
referrer	The ID of the customer who shared the URL that led to the visit.	no	string
type	Additional media-related information.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "visit",
   "data":  {
       "url": "https://www.example.com/summer-styling-tips24",
       "type": "Blog pages"
   }

}

contest_entry_revoke

Minimal Buttons

This event revokes a customer’s entry or multiple entries from a contest managed in the Contest lite module.

Attribute	Description	Required	Type
contest_id	The unique identifier of the contest from which entries will be revoked.	yes	string
refund_points	A boolean flag indicating whether loyalty points spent on contest entries will be refunded to the customer. Points spent on contest entries are typically refunded if the entry is revoked.	yes	boolean
count	The number of contest entries to be revoked for the customer.	yes	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "contest_entry_revoke",
   "data":  {
       "contest_id": "64ad0b15469c715a16193739",
       "refund_points": 20,
     	 "count": 1
   }

}

pending

This event sets the status of specific points associated with an event to pending. It is automatically registered when an event is submitted, which, according to the Pending events module settings, must first be placed in a pending status.

Attribute	Description	Required	Type
event	Specifies the event whose status and associated attributes will be set to pending.	yes	object

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "pending",
   "data":  {
       "event": "6ea20b30469d715a161973929"
   }

}

referral

This event is registered in the customer’s event history when a referred friend completes a purchase to the customer’s invitation.

Attribute	Description	Required	Type
referred	The unique ID of the customer who completed a purchase after being referred.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "referral",
   "data":  {
       "referred": "280e674c-de2a-4a30-987a-d9267d1a119"
   }

}

referral_bonus

Minimal Buttons

This event awards bonus points to customers who successfully refer a friend.

Attribute	Description	Required	Type
points	The number of points awarded as a referral bonus.	yes	numeric
reason	The reason for awarding the referral bonus points.	no	string
referred	The ID of the customer who completed a purchase after being referred by the referrer customer.	no	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "referral",
   "data":  {
       "referred": "280e674c-de2a-4a30-987a-d9267d1a119",
     	 "points": 200
   }

}

reward_revoke

Minimal Buttons

This event revokes a reward and resets the claim statistics for both the customer and the reward.

For redeemed coupons, ensure they are unredeemed (using coupon_unredeem) before submitting this event.

Attribute	Description	Required	Type
event	The unique ID of the event recording the reward claim.	yes	string
club_id	A unique identifier of club (if any) associated with the reward claim event.	no	string
club_points	The number of points spent from the club balance (if any) for claiming the reward.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "reward_revoke",
   "data":  {
       "event": "6be30b73969d925v161289129"
   }

}

reward_transfer

Minimal Buttons

This event facilitates the transfer of a claimed reward from one customer to another. It can only be initiated for rewards configured with the Transferable flag enabled on the Management UI reward configuration interface.

Attribute	Description	Required	Type
target	The unique ID of the customer who will receive the reward.	no	string
email	The email address of the customer receiving the reward. Checked only if provided. If both `target` and `email` are sent, they must match the same customer. The email must be unique, otherwise the reward transfer fails.	no	string
reward	The unique ID of the reward being transferred.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "reward_transfer",
   "data":  {
    	"target": "280e674c-de2a-4a30-987a-d9267d1a119",
    	"email": "[email protected]",
	"reward": "65b8f82a88b456710a44e84a"
   }

}

prize_wheel_spin

Minimal Buttons

This event records when a customer spins a prize wheel configured in the Prize wheels module.

Attribute	Description	Required	Type
wheel	The unique ID of the prize wheel.	yes	string
result	The unique ID of the prize wheel slice that the customer landed on during the prize wheel spin. You can use the Retrieve all slices for a specific prize wheel API endpoint to list the slice ID and additional information for all slices of a specific prize wheel.	yes	string
type	Specifies the type of slice the customer landed on during the prize wheel spin, which can be nothing or reward.	yes	string
points	The number of points spent by the customer for spinning the prize wheel.	no	numeric

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "prize_wheel_spin",
   "data":  {
         "wheel": "67f4d06810b04c29210bb00b",
     	 "result": "67f4d5ba5620b1f97302a248",
     	 "type": "reward"
   }
}

tiered_campaign_pending

Minimal Buttons

This event logs the accumulation of pending points for customers during a tiered campaign.

Attribute	Description	Required	Type
campaign	The unique ID associated with the tiered campaign.	yes	string
pending_points	The number of pending points.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "tiered_campaign_pending",
   "data":  {
       "campaign": "65a52f3a40697c53595a86e9",
     	 "pending_points": 126
   }

}

tiered_campaign_award

Minimal Buttons

This event triggers the awarding of points to the customer in a tiered campaign after the grace period, ensuring they are no longer pending.

Attribute	Description	Required	Type
campaign	The unique ID associated with the tiered campaign.	yes	string
points_rewarded	Number of points awarded for the campaign participation.	yes	string
iteration	A campaign might repeat multiple times throughout its duration. This attribute represents the specific occurrence within a tiered campaign.	yes	string
expired_points	The number of points that have expired.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "tiered_campaign_award",
   "data":  {
       "campaign": "65a52f3a40697c53595a86e9",
     	 "points_rewarded": 126,
     	 "iteration": "2",
     	 "expired_points": 0
   }

}

draft_transaction

Minimal Buttons

When any event with a unique transaction_id is submitted, it creates a draft transaction. To finalize this transaction, submit a checkout event with the same transaction_id.

This event can also be registered during the initial OCR scanning state in Klippa before it is converted to digital data.

This event requires the Checkout accept module to be enabled.

Attribute	Description	Required	Type
transaction_id	This unique ID is used to identify the draft transaction.	yes	string

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

{
   "customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
   "action": "draft_transaction",
   "data":  {
       "transaction_id": "TR37882412"
   }

}