Events API #

A purchase of any product or service. This existing list of attributes can be extended using the Custom Events module of Antavo, allowing the tracking of other attributes and establishment of different loyalty logic and journeys.

The automatic awarding of points for checkout requires the Incentivized purchase / Points economy modules. When enabled, customers’ points are not awarded for the checkout itself as points are only granted after each checkout line item, the corresponding checkout_item event. The checkout event will also trigger the release of any reserved points. See also: Checkout

Note

The checkout event can be extended by the activated Checkout accept or pending module. In these scenarios, the resulting transaction from a submitted checkout is assigned a pending status and an additional step accepts/rejects the transaction.

Attributes

Name	Type	Required	Module	Description
auto_accept	date	No	built-in	An optional field which overrides the default auto_accept date with the supplied date
transaction_id	string	Yes	built-in	A unique code that is used for identifying each transaction. An event submission with a preexisting transaction_id will be rejected as a duplicate with the ERR_TX_ALREADY_EXISTS error message
total	number	Yes	built-in	The overall sum paid by the customer during the checkout.
items	string array	No	built-in	A collection of line items describing the product or service that was purchased. checkout_item consists of multiple separate sub-properties.
points_burned	integer	No	built-in	The amount of loyalty points customers has used in the transaction. Antavo will automatically remove these points from the customer upon a successful event submission. The event will be rejected if points_burned is larger than the customer’s available points balance. Despite not being able to give points for them, checkouts can still have a negative points value assigned to them due to points_burned.
channel	string	No	built-in	Under channel, you can send in any platform you wish to track, such as “store”, “mobile”, or “online”, or more specific channels, like “POS” or “API”.
currency	string	No	built-in	Currency Code You can describe the currency used for the transaction in multiple ways, but the 3-character currency code is preferred: USD, EUR, GBP
country	string	No	built-in	The country where the checkout was made.
discount	string	No	built-in	The amount of discount applied to the purchase. It’s useful to send this information in case you would like to offer points after purchases made without any discounts.
shipping	integer	No	built-in	Records the cost of the shipping. Antavo LMP can give customer bonus points depending on shipping costs.
total_quantity	integer	No	checkout_accept	The total quantity for the checkout.
points_rewarded	integer	No	checkout_accept	A custom number of positive integer points awarded for purchasing a certain product which overrides the default subtotal-based behavior provided by Antavo Incentivized Purchase module.
store	string	No	store	The name of the store. This is commonly used for physical in-store purchases. This process can be simplified by using the Store Management module. Stores can be registered in the Store Management module, each of them receives a Store ID which can be used in this store property.
coupon_code	string	No	coupon	A coupon code which will be automatically redeemed upon a successful checkout event submission
coupons	array	No	coupon	An array of coupon codes which will be automatically redeemed upon a successful checkout event submission
offers	array	No	offers	An array of offers which are associated with the current transaction.
purchase_date_timestamp	string	No	shopify
computed_total_quantity	integer	No	shopify	Calculated total quantity of checkout items in a checkout
shipping_shop_money_amount	integer	No	shopify

Example

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

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

}

Errors

Error Code	Message	Description
0	Property <attribute> cannot be empty	A required field is empty
0	Customer doesn’t have enough points for discount	The number of points to be burned are greater than the customer’s spendable points
5003	ERR_TX_ALREADY_EXISTS	The transaction ID has already be used

checkout_accept#

The checkout approval mechanism for pending checkouts, created using a standard checkout event in conjunction with the checkout_accept module. The event and its associated checkout_accept_item can be extending using the custom events module to contain fields/values present in the original checkout/checkout_item event. These can be subsequently used in workflows and/or challenges but can not be modified by this event. checkout_update should be used for making modification to transactions. See also: Checkout accept

Attributes

Name	Type	Required	Module	Description
transaction_id	string	Yes	checkout_accept	The transaction id for the pending checkout event to be approved.

Example

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

{
   "customer": "demo_customer_id",
   "action": "checkout_accept",
   "data":  {
       "transaction_id": "<unique_transaction_id>"
   }

}

Errors

Error Code	Message	Description
0	Property transaction_id cannot be empty	No transaction ID was sent
911001	Transaction not found	Checkout event with same transaction_id was not located in the database. This transaction has not been received has been already accepted/rejected

checkout_accept_item#

Internal Antavo event - Accepts line items for the purchase, including detailed information about the product name, product category, SKU, quantity and price. All information in this event comes from the corresponding checkout_item and checkout_update_item events . This event can not be directly submitted but is created from a checkout_accept event

Attributes

Name	Type	Required	Module	Description
product_id	string	Yes	built-in	This must be identical to product ID values in all non-Antavo system
product_name	string	Yes	built-in	The name of the item in any non-Antavo system
product_url	string	Yes	built-in	The web address that points to the item’s online store page.
quantity	integer	Yes	built-in	The exact number of items that were purchased during the checkout.
points_rewarded	integer	No	built-in	A custom number of positive integer points awarded for purchasing a certain product which overrides the default subtotal-based behavior provided by Antavo Incentivized Purchase module.
subtotal	number	Yes	built-in	The overall amount paid during the checkout.
price	number	No	built-in	The full value of a single item before discount. The value has to be entered and is not calculated by Antavo.
discount	number	No	built-in	The reduction made to the original price during the checkout.
product_category	string	No	built-in	Any number of categories or subcategories that match the product.

checkout_claim#

transaction

This event claims a guest transaction based upon the submitted transaction_id.

Attributes

Name	Type	Required	Module	Description
transaction_id	string	Yes	Customer ID validation	The unique transaction ID of a submitted guest checkout.

checkout_item#

Internal Antavo event - Defines line items for the purchase, including detailed information about the product name, product category, SKU, quantity and price. These pre-existing properties can be expanded by using custom fields. This event can not be directly submitted but is created from items in a checkout event. The checkout_item also inherits every checkout attribute.

Points are only automatically awarded based upon the value of the subtotal. Only elements submitted in the event are recorded – Antavo does not calculate any checkout_item attributes. All elements can, however, be accessed from the event and used elsewhere in the loyalty management platform. It is strongly recommended that the subtotal is externally calculated in the following way:

\((price - discount) \times quantity = subtotal\)

Attributes

Name	Type	Required	Module	Description
product_id	string	Yes	built-in	This must be identical to product ID values in all non-Antavo system
product_name	string	Yes	built-in	The name of the item in any non-Antavo system
product_url	string	Yes	built-in	The web address that points to the item’s online store page.
quantity	integer	Yes	built-in	The exact number of items that were purchased during the checkout.
points_rewarded	integer	No	built-in	A custom number of positive integer points awarded for purchasing a certain product which overrides the default subtotal-based behavior provided by Antavo Incentivized Purchase module.
subtotal	number	Yes	built-in	The overall amount paid during the checkout.
price	number	No	built-in	The full value of a single item before discount. The value has to be entered and is not calculated by Antavo .
discount	number	No	built-in	The reduction from the original price during the checkout.
product_category	string	No	built-in	Any number of categories or subcategories that match the product.

checkout_reject#

The checkout rejection mechanism for pending checkouts, created using a standard checkout event in conjunction with the checkout_accept module.

Attributes

Name	Type	Required	Module	Description
transaction_id	string	Yes	checkout_accept	The transaction id for the pending checkout event to be rejected.

Example

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

{
   "customer": "demo_customer_id",
   "action": "checkout_reject",
   "data":  {
       "transaction_id": "<unique_transaction_id>"
   }

}

Errors

Error Code	Message	Description
0	Property transaction_id cannot be empty	No transaction ID was sent
911001	Transaction not found	Checkout event with same transaction_id was not located in the database. This transaction has not been received has been already accepted/rejected

checkout_update#

This event updates information within a pending checkout before checkout approval using checkout_update_item events. This is the only way to remove items from a pending checkout. See also: Checkout accept

Attributes

Name	Type	Required	Module	Description
auto_accept	date	No	built-in	An optional field which overrides the default auto_accept date with the supplied date. Submitting a NULL or empty string will result in the checkout event needing to be manually accepted/denied.
total	number	Yes	checkout_accept	Modify the total of the pending checkout
transaction_id	string	Yes	checkout_accept	The transaction id for the pending checkout to be modified.
items	string array	No	built-in	A collection of line items describing the product or service that was purchased. checkout_update_item consists of multiple separate sub-properties.
points_burned	integer	No	built-in	The amount of loyalty points customers has used in the transaction. Antavo will automatically remove these points from the customer upon a successful event submission. The event will be rejected if points_burned is larger than the customer’s available points balance. Checkouts can have a negative points value assigned to them due to points_burned.
channel	string	No	built-in	Under channel, you can send in any platform you wish to track, such as “store”, “mobile”, or “online”, or more specific channels, like “POS” or “API”.
currency	string	No	built-in	Currency Code You can describe the currency used for the transaction in multiple ways, but the 3-character currency code is preferred: USD, EUR, GBP
country	string	No	built-in	The state where the checkout was made.
discount	string	No	built-in	The amount of discount applied to the purchase. It’s useful to send this information in case you would like to offer points after purchases made without any discounts.
shipping	integer	No	built-in	Add this property if you wish to send in the cost of the shipping. Antavo LMP can give customer bonus points depending on shipping costs.
store	string	No	Store	The name of the store. This is commonly used for physical in-store purchases. This process can be simplified by using the Store Management module. Stores can be registered in the Store Management module, each of them receives a Store ID which can be used in this store property.

Example

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

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

}

Errors

Error Code	Message	Description
0	Property transaction_id cannot be empty	No transaction ID was sent
911001	Transaction not found	Checkout event with same transaction_id was not located in the database. This transaction has not been received has been already accepted/rejected

checkout_update_item#

Internal Antavo event - Updates line items for the purchase, including detailed information about the product name, product category, SKU, quantity and price. This pre-existing properties can be expanded by using custom fields. This event can not be directly submitted but is created from items in a checkout_update event

Attributes

Name	Type	Required	Module	Description
product_id	string	Yes	built-in	This must be identical to product ID values in all non-Antavo system
product_name	string	Yes	built-in	The name of the item in any non-Antavo system
product_url	string	Yes	built-in	The web address that points to the item’s online store page.
quantity	integer	Yes	built-in	The exact number of items that were purchased during the checkout.
points_rewarded	integer	No	built-in	A custom number of positive integer points awarded for purchasing a certain product which overrides the default subtotal-based behavior provided by Antavo Incentivized Purchase module.
subtotal	number	Yes	built-in	The overall amount paid during the checkout.
price	number	No	built-in	The full value of a single item before discount. The value has to be entered and is not calculated by Antavo.
discount	number	No	built-in	The reduction made to the original price during the checkout.
product_category	string	No	built-in	Any number of categories or subcategories that match the product.

contest_entry_revoke#

A number of entries into a contest-lite competition are revoked for a give customer

Attributes

Name	Type	Required	Description
contest_id	string	No	The ID of the contest
refund_points	boolean	No	Should points be returned to the customer?
count	number	No	The number of entries to be revoked

Example

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

{
   "customer": "demo_customer_id",
   "action": "contest_entry_revoke",
   "data":  {
       "contest_id": "aabbccddeeffgghh",
       "refund_points": 1
   }

}

coupon#

Creates and assigns a coupon with the given code to the customer. Only available through the coupons module. Deprecated use coupon_create

Attributes

Name	Type	Required	Module	Description
code	string	Yes	built-in	The coupon code to be generated.
amount	number	No	built-in	The value of the coupon
expiration_date	date	No	built-in	the expiration date of the coupon

coupon_create#

An extended mechanism where coupons can be created and assigned with additional informative data. Only available through the coupons module.

Attributes

Name	Type	Required	Module	Description
code	string	Yes	built-in	The coupon code to be generated.
name	string	No	built-in	The name of the coupon
currency	string	No	built-in	The currency of the coupon
type	selection	No	built-in	The type of coupon - amount, percentage or free shipping
amount	number	No	built-in	The value of the coupon
expdate	date	No	built-in	The expiration date of the coupon
pool	string	No	built-in	select corresponding coupon pool
stores	string	No	built-in	Add Antavo stores identifiers to the coupon
product	string	No	built-in	Add Antavo product identifiers to the coupon
cost	number	No	built-in	The associated business cost for the coupon
value	number	Yes	built-in	The value of the coupon

Example

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

{
   "customer": "demo_customer_id",
   "action": "coupon_create",
   "data":  {
       "code": "ABC-DEF",
       "name": "Test coupon",
       "currency": "GBP",
       "type": "amount",
       "value": 10
   }

}

coupon_invalidate#

The specified coupon is invalidated

Attributes

Name	Type	Required	Module	Description
code	string	Yes	built-in	The code of the coupon to be invalidated

Example

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

{
   "customer": "demo_customer_id",
   "action": "coupon_invalidate",
   "data":  {
       "code": "ABC-DEF"
   }

}

coupon_receive#

Internal Antavo event - An event written to a customer’s event stream when a coupon has been transferred to them

Attributes

Name	Type	Required	Module	Description
code	string	No		The coupon Code
original	string	No		The Antavo ID of original owner of the coupon

Example

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

{
   "customer": "demo_customer_id",
   "action": "coupon_receive",
   "data":  {
       "code": "C3-PO",
       "original": "Anakin Skywalker"
   }

}

coupon_redeem#

This event marks a coupon as redeemed, using the timestamp of the event. Only available through the coupons module. The coupon redeem process can be automatically triggered for uploaded coupons in a coupon pool. The configuration settings are described in the user manual <>.

Attributes

Name	Type	Required	Module	Description
code	string	Yes	built-in	The coupon code to be redeemed.
transaction_id	string	No	built-in	The corresponding transaction used when redeeming the coupon
amount	number	Yes	built-in	The value of the coupon. This is only required for multiple use gift card coupons and can be any value between 0 and the value of the coupon’s balance field.
cost	number	No	built-in	The associated business cost for the coupon

Example

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

{
   "customer": "demo_customer_id",
   "action": "coupon_redeem",
   "data":  {
       "code": "abc-def-123-456"
   }

}

Errors

Error Code	Message	Description
1601	Coupon not found	Coupon not found
1606	The coupon balance is lower than the amount	The value being redeemed is greater than the gift card’s balance

coupon_transfer#

This event transfers a coupon from one customer to another.

Attributes

Name	Type	Required	Description
code	string	No	The code of the coupon to be transferred.
email	string	No	The email address of the target customer. An inactive customer will be created if the email address does not match an Antavo user.
target	string	No	The Antavo ID of the target customer.
reward_id	string	No	The unique Antavo ID of the reward issuing the coupon.

Example

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

{
   "customer": "demo_customer_id",
   "action": "coupon_transfer",
   "data":  {
       "code": "keys2deathstar",
       "email": null,
       "target": "skywalker",
       "reward_id": "deathstarplans1"
   }

}

coupon_unredeem#

pending events transaction

This event restores a coupon to a pre-redeemed state. Only available through the coupons module.

Attributes

Name	Type	Required	Module	Description
code	string	Yes	built-in	The coupon code to be restored.

Example

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

{
   "customer": "demo_customer_id",
   "action": "coupon_unredeem",
   "data":  {
       "code": "abc-def-123-456"
   }

}

merge#

Internal Antavo event - The customer’s profile has been merged with another customer. This event is recorded automatically by Antavo on the target customer’s profile

Attributes

Name	Type	Required	Module	Description
source	string	Yes	built-in	The source account to be merged

Example

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

{
   "customer": "demo_customer_id",
   "action": "merge",
   "data":  {
       "source": "Another_account_ID"
   }

}

Name	Type	Required	Module	Description
campaign	string	Yes	NewsletterTracking
url	string	Yes	NewsletterTracking

Name	Type	Required	Module	Description
campaign	string	Yes	NewsletterTracking

offer_redeem#

This event records that customer has redeemed a stated offer

Attributes

Name	Type	Required	Module	Description
offer	string	Yes	offers	The offer’s unique ID

Example

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

{
   "customer": "demo_customer_id",
   "action": "offer_redeem",
   "data":  {
       "offer": "aabbccddeeffgghh"
   }

}

offer_unredeem#

This event records that customer has unredeemed a stated offer

Attributes

Name	Type	Required	Module	Description
offer	string	Yes	offers	The offer’s unique ID

Example

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

{
   "customer": "demo_customer_id",
   "action": "offer_unredeem",
   "data":  {
       "offer": "aabbccddeeffgghh"
   }

}

offline_treasure_code_found#

Offline treasure code has been found by the customer.

Attributes

Name	Type	Required	Module	Description
treasure_id	string	Yes	built-in	The ID of the treasure

Example

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

{
   "customer": "demo_customer_id",
   "action": "offline_treasure_code_found",
   "data":  {
       "treasure_id": "Herebethemap",
       "code": "Herebethetreasure"
   }

}

offline_treasure_found#

Offline treasure has been found by the customer.

Attributes

Name	Type	Required	Module	Description
treasure_id	string	Yes	built-in	The ID of the treasure

Example

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

{
   "customer": "demo_customer_id",
   "action": "offline_treasure_found",
   "data":  {
       "treasure_id": "Herebegold"
   }

}

opt_in#

A customer enrolls in the loyalty program. This is usually the first registered event of any customer in Antavo and thus the submitted customer string will become the unique identifier for the newly created customer.

Attributes

Name	Type	Required	Module	Description
email	string	Yes	built-in	A valid email address of the loyalty program member
first_name	string	No	built-in	The first name of the loyalty program member. This can be used as a personalization token for emails and newsletters.
last_name	string	No	built-in	The last name of the loyalty program member.
handler	string	No	built-in	The nickname that would appear on the user profile.
language	string	No	built-in	An ISO 639-2 Code to identify the language of the loyalty member. Any value can be used, but a recognized language code may result in the loyalty page in the user’s language, if available.
currency	string	No	built-in	The preferred currency in an ISO 4217 code format. E.g., USD, EUR, GBP
birth_date	DateString	No	built-in	Year, month and day. (YYYY-MM-DD). An invalid date entry will result in the event submission being rejected
referrer	string	No	Friend referral	The unique account id of the customer who referred the newly-joining customer to the loyalty scheme

Example

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

{
   "customer": "demo_customer_id",
   "action": "opt_in",
   "data":  {
       "email": "starkiller@example.com",
       "first_name": "Luke",
       "last_name": "Skywalker",
       "handler": "Rogue1",
       "referrer": "OB1"
   }

}

opt_out#

GDPR compliant opt-out of a customer from loyalty program. All information that could identify the customer is hashed and is non- recoverable. Transaction related information remains, but the customer is unidentifiable.

Attributes

Name	Type	Required	Module	Description
reason	string	No	built-in	A reason can be given for leaving the loyalty program

Example

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

{
   "customer": "demo_customer_id",
   "action": "opt_out",
   "data":  {
       "reason": "Broke terms and conditions"
   }

}

partial_refund#

refund transaction

A refund event which enables a specified total to be refunded. This value is usually less than the full transaction amount. Only transactions with an accepted status can be refunded. The following actions occur for a successfully submitted event:

The appropriate amount is removed from all transaction details
The customer score is reduced. There is no change in customer spent.
Any burned points are restored using the point_unburn event
Transaction’s earned & burned properties are updated
The customer’s expiring points are updated

Attributes

Name	Type	Required	Module	Description
transaction_id	string	Yes	built-in	A unique code that is used for identifying the refunded event
amount	numeric	Yes	built-in	The value of the partial refund

Example

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

{
   "customer": "demo_customer_id",
   "action": "partial_refund",
   "data":  {
       "transaction_id": "<unique_transaction_id>",
       "amount": 140
   }

}

pending#

Internal Antavo event - An event to create a pending event.

Attributes

Name	Type	Required	Module	Description
event	string	Yes	pending events	The event id to be made pending.

pending_expired#

Invalidates the specified pending event using the pending_event module and records the event into the customer’s event history

Attributes

Name	Type	Required	Module	Description
points	numeric	Yes	pending events	The pending points that have expired

pending_invalidate#

pending events transaction

Invalidates the specified pending event using the pending_event module and records the event into the customer’s event history

Attributes

Name	Type	Required	Module	Description
event	string	Yes	pending events	The pending event id to be invalidated

Example

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

{
   "customer": "demo_customer_id",
   "action": "pending_invalidate",
   "data":  {
       "event": "aabbccddeeffgghh"
   }

}

pending_validate#

pending events transaction

Validates the specified pending event using the pending_event module and records the event into the customer’s event history

Attributes

Name	Type	Required	Module	Description
event	string	Yes	pending events	The pending event id to be validated

Example

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

{
   "customer": "demo_customer_id",
   "action": "pending_validate",
   "data":  {
       "event": "aabbccddeeffgghh"
   }

}

point_add#

Adjusts the customer’s point balance by adding points. This increases the customer’s all time collected points (score). Admins can use this event to manually correct a customer’s score in the case of misalignment.

Attributes

Name	Type	Required	Module	Description
points	integer	Yes	built-in	A positive number to be added the customer’s overall score
reason	string	No	built-in	Describe the motive behind point_add. For internal purposes only
transaction_id	string	No	built-in	Associates the submitted event with the specified transaction_id and it will appear in the transaction’s detailed breakdown

Example

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

{
   "customer": "demo_customer_id",
   "action": "point_add",
   "data":  {
       "points": 100,
       "reason": "The customer was extremely nice and polite"
   }

}

point_spend#

Adjusts the customer’s point balance by subtracting points. This action does not affect customer’s all time collected points (score) and mimics redeeming points at checkout or redeeming a reward. Admins can use this event to manually change the customer’s point balance in a way that it’s trackable in the point history.

Attributes

Name	Type	Required	Module	Description
points	integer	Yes	built-in	The number of points to be spent. Only positive integers are accepted.
reason	string	No	built-in	Describe the motive behind point_spend. For internal purposes only.
transaction_id	string	No	built-in	Associates the submitted event with the specified transaction_id and it will appear in the transaction’s detailed breakdown

Example

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

{
   "customer": "demo_customer_id",
   "action": "point_spend",
   "data":  {
       "points": 100,
       "reason": "Customer service correction"
   }

}

point_sub#

Adjusts the customer’s point balance by removing points. This decreases the customer’s all time collected points (score). Admins can use this event to manually correct a customer’s score in the case of misalignment.

Attributes

Name	Type	Required	Module	Description
points	integer	Yes	built-in	The number of points to be subtracted from the score. Only positive integers are accepted.
reason	string	No	built-in	Describe the motive behind point_sub. For internal purposes only.

Example

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

{
   "customer": "demo_customer_id",
   "action": "point_sub",
   "data":  {
       "points": 100,
       "reason": "Customer services were too generous with point_add"
   }

}

point_unspend#

Adjusts the customer’s point balance by adding points. This action does not affect customer’s all time collected points (score) and mimics refunding points or revoking a reward. Admins can use this event to manually change the customer’s point balance in a way that it’s trackable in the point history.

Attributes

Name	Type	Required	Module	Description
points	integer	Yes	built-in	The number of points to be added to the customer. Only positive integers are accepted.
reason	string	No	built-in	Describe the motive behind point_unspend. For internal purposes only.
transaction_id	string	No	built-in	Associates the submitted event with the specified transaction_id and it will appear in the transaction’s detailed breakdown

Example

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

{
   "customer": "demo_customer_id",
   "action": "point_unspend",
   "data":  {
       "points": 100,
       "reason": "Customer service correction"
   }

}

prize_wheel_spin#

Internal Antavo event - The spin of a specified prizewheel, using the prizewheels module

Attributes

Name	Type	Required	Module
wheel	string	Yes	prizewheels
result	string	Yes	prizewheel
type	string	Yes	prizewheel
points	numeric	No	prizewheel

profile#