> For the complete documentation index, see [llms.txt](https://docs.tallymarks.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tallymarks.io/api-documentation/event-api.md). # Event API Events are triggered by your own site or application, typically in response to a customer’s activity, such as registering, ordering or completing a transaction. Integrate your existing platforms with the Tallymarks Event API to capture, assess and fulfil your customer events. Also see [Swagger based Event API documentation](https://api-event.tallymarks.net/swagger/index.html) {% hint style="info" %} **Creating Customers** The minimum information required to create a Customer is a CustomerId (a unique Guid/UUID in the form 00000000-0000-0000-0000-000000000000). The Event APIs will automatically create a customer record if they are provided with a CustomerId that has previously not been created in the platform. Customer records can be enhanced using the Customer API. {% endhint %} ## Create Action Represent simple event notification that takes place in response to a customer’s activity. For example: * Customer Registration * Unsubscribe * Refer a Friend * Access a Page or Product * Complete a Survey The Action event is assessed against "Action" assessment rules and if matched fulfilment rules are applied. This processing of the event is **asynchronous**. ### POST ``` /api/v1/events/actions ``` #### Request | Element | Type | Description | | ------------------ | --------- | ----------------------------------------------------------------------- | | action.amount | decimal | Represents an amount related to the action | | action.count | integer | Represent a counter related to the action | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | nameSpace | string | A namespace to represent the event, for example "Customer.Registration" | | reference | string | An external reference number | | campaign | string | An campaign identifier | | attributes\[] | List | A list of attributes | | attributes\[]key | string | Attribute Key | | attributes\[]value | string | Attribute Value | ``` { "action": { "amount": 0, "count": 0 }, "eventId": "string", "customerId": "string", "nameSpace": "string", "reference": "string", "campaign": "string", "attributes": [ { "key": "string", "value": "string" } ] } ``` #### Response: 200 | Event | Type | Description | | ---------- | --------- | ------------------------------------ | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | tenantId | guid/uuid | A unique identifier for the tenant | | isExisting | bool | True if the eventId already existed | ``` { "eventId": "string", "customerId": "string", "tenantId": "string", "isExisting": true } ``` ## Assess Basket Represent an event notification that supports the **assessment** of a customer's ecommerce shopping basket. The Basket event is assessed against "Basket" assessment rules and if matched fulfilment rules are returned **synchronously** as a response. **No** fulfilment takes place. ### POST ``` /api/v1/events/basket ``` #### Request | Element | Type | Description | | ------------------------------ | --------------- | ----------------------------------------------------------------------------------- | | basketId | guid/uuid | A unique identifier for the basket | | customerInfo | string | An order status, for example "In Picking" | | customerInfo.ExternalReference | string | Customer External Reference | | currencyCode | string | A ISO Currency Code | | basketTotal | decimal | Total order in Currency. Is the value use in Annual and Lifetime spend calculation | | taxTotal | decimal | Total tax | | shippingTotal | decimal | Total cost of shipping | | rewardsEligibleTotal | decimal | A custom total amount of the order that is eligible for rewards calculations. | | basketItems\[] | Array | An order item | | basketItems\[].orderLineId | int | An identifier for the order line | | basketItems\[].quantity | int | Quantity of product in order line | | basketItems\[].itemPrice | decimal | Price for the product in the order line | | basketItems\[].productId | string | An identifer for the Product | | basketItems\[].sku | string | An sku (stock-keeping unit) for the Product | | basketItems\[].vendor | string | The vendor for the Product. | | basketItems.tags\[] | Array | Array of tags (as string) | | basketItems.attributes\[] | Array | Array of attributes | | basketItems.attributes\[]key | string | Key | | basketItems.attributes\[]value | string | Value | | surcharges\[] | Array | Surcharges | | surcharge.name | string | Surcharge Name | | surcharge.amount | decimal | Surcharge Amount | | billingAddress | billingAddress | Billing Address Detail | | billingAddress.street1 | string | Address Line 1 | | billingAddress.street2 | string | Address Line 2 | | billingAddress.city | string | City or Suburb, e.g. Ultimo | | billingAddress.state | string | State, e.g. New South Wales | | billingAddress.stateCode | string | State Code, e.g. NSW | | billingAddress.country | string | Country, e.g. Australia | | billingAddress.countryCode | string | ISO Country Code e.g. AU | | billingAddress.postalCode | string | Postal or Zip Code | | billingAddress.phoneNumber | string | Phone Number | | shippingAddress | shippingAddress | Shipping Address Detail | | shippingAddress.street1 | string | Address Line 1 | | shippingAddress.street2 | string | Address Line 2 | | shippingAddress.city | string | City or Suburb, e.g. Ultimo | | shippingAddress.state | string | State, e.g. New South Wales | | shippingAddress.stateCode | string | State Code, e.g. NSW | | shippingAddress.country | string | Country, e.g. Australia | | shippingAddress.countryCode | string | ISO Country Code e.g. AU | | shippingAddress.postalCode | string | Postal or Zip Code | | shippingAddress.phoneNumber | string | Phone Number | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | nameSpace | string | A namespace to represent the event, for example "Customer.Registration" | | reference | string | An external reference number | | campaign | string | An campaign identifier | | attributes\[] | Array | A list of attributes | | attributes\[]key | string | Attribute Key | | attributes\[]value | string | Attribute Value | ``` { "basket": { "basketId": "string", "customerInfo": { "externalReference": "string" }, "currencyCode": "string", "basketTotal": 0, "taxTotal": 0, "shippingTotal": 0, "basketItems": [ { "basketItemId": "string", "basketItemParts": [ { "basketItemPartId": "string", "quantity": 0, "itemPrice": 0, "totalPrice": 0, "productId": "string", "sku": "string", "name": "string", "vendor": "string", "tags": [ "string" ], "keyValues": [ { "key": "string", "value": "string" } ] } ], "quantity": 0, "itemPrice": 0, "totalPrice": 0, "productId": "string", "sku": "string", "name": "string", "vendor": "string", "tags": [ "string" ], "keyValues": [ { "key": "string", "value": "string" } ] } ], "surcharges": [ { "name": "string", "amount": 0 } ], "billingAddress": { "street1": "string", "street2": "string", "city": "string", "state": "string", "stateCode": "string", "country": "string", "countryCode": "string", "postalCode": "string", "phoneNumber": "string" }, "shippingAddress": { "street1": "string", "street2": "string", "city": "string", "state": "string", "stateCode": "string", "country": "string", "countryCode": "string", "postalCode": "string", "phoneNumber": "string" } }, "eventId": "string", "tenantId": "string", "customerId": "string", "createdAt": "2020-05-15T11:55:47.515Z", "nameSpace": "string", "reference": "string", "description": "string", "campaign": "string", "attributes": [ { "key": "string", "value": "string" } ] } ``` ## Create Order Represent an event notification that takes place in response to a customer placing an order. The Order event is assessed against "Order" or "Spend" assessment rules and if matched fulfilment rules are applied. This processing of the event is **asynchronous**. ### POST ``` /api/v1/events/orders ``` #### Request | Element | Type | Description | | ------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------- | | orderId | guid/uuid | A unique identifier for the order | | orderStatus | string | An order status, for example "In Picking" | | financialStatus | string | A financial status, for example "Invoiced", "Paid" | | currencyCOde | string | A ISO Currency Code | | total | decimal | Total order in Currency. Is the value use in Annual and Lifetime spend calculation | | taxTotal | decimal | Total tax | | shippingTotal | decimal | Total cost of shipping | | rewardsEligibleTotal | decimal | A custom total amount of the order that is eligible for rewards calculations. | | orderItems\[] | Array | An order item | | orderItems\[].orderLineId | int | An identifier for the order line | | orderItems\[].quantity | int | Quantity of product in order line | | orderItems\[].itemPrice | decimal | Price for the product in the order line | | orderItems\[].productId | string | An identifer for the Product | | orderItems\[].sku | string | An sku (stock-keeping unit) for the Product | | orderItems\[].vendor | string | The vendor for the Product. | | orderItems.paymentDetail | paymentDetail | Payment Details | | orderItems.paymentDetail.bin | string | Bin | | orderItems.paymentDetail.bank | string | Bank | | orderItems.paymentDetail.scheme | string | Schem | | paymentDetail.segmentation | string | Segmentation | | paymentDetail.paymentAmount | decimal | Payment Amount | | paymentDetail.redemptionDetail | redemptionDetail | | |

paymentDetail.
redemptionDetail.pointsAmount

| decimal | Points component of Order | | billingAddress | billingAddress | Billing Address Detail | | billingAddress.street1 | string | Address Line 1 | | billingAddress.street2 | string | Address Line 2 | | billingAddress.city | string | City or Suburb, e.g. Ultimo | | billingAddress.state | string | State, e.g. New South Wales | | billingAddress.stateCode | string | State Code, e.g. NSW | | billingAddress.country | string | Country, e.g. Australia | | billingAddress.countryCode | string | ISO Country Code e.g. AU | | billingAddress.postalCode | string | Postal or Zip Code | | billingAddress.phoneNumber | string | Phone Number | | shippingAddress | shippingAddress | Shipping Address Detail | | shippingAddress.street1 | string | Address Line 1 | | shippingAddress.street2 | string | Address Line 2 | | shippingAddress.city | string | City or Suburb, e.g. Ultimo | | shippingAddress.state | string | State, e.g. New South Wales | | shippingAddress.stateCode | string | State Code, e.g. NSW | | shippingAddress.country | string | Country, e.g. Australia | | shippingAddress.countryCode | string | ISO Country Code e.g. AU | | shippingAddress.postalCode | string | Postal or Zip Code | | shippingAddress.phoneNumber | string | Phone Number | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | nameSpace | string | A namespace to represent the event, for example "Customer.Registration" | | reference | string | An external reference number | | campaign | string | An campaign identifier | | attributes\[] | Array | A list of attributes | | attributes\[]key | string | Attribute Key | | attributes\[]value | string | Attribute Value | ``` { "order": { "orderId": "string", "orderStatus": "string", "financialStatus": "string", "currencyCode": "string", "total": 0, "taxTotal": 0, "shippingTotal": 0, "rewardsEligibleTotal": 0, "orderItems": [ { "orderLineId": 0, "quantity": 0, "itemPrice": 0, "productId": "string", "sku": "string", "name": "string", "vendor": "string" } ], "paymentDetail": { "bin": "string", "bank": "string", "scheme": "string", "segmentation": "string", "paymentAmount": 0 }, "redemptionDetail": { "pointsAmount": 0 }, "billingAddress": { "street1": "string", "street2": "string", "city": "string", "state": "string", "stateCode": "string", "country": "string", "countryCode": "string", "postalCode": "string", "phoneNumber": "string" }, "shippingAddress": { "street1": "string", "street2": "string", "city": "string", "state": "string", "stateCode": "string", "country": "string", "countryCode": "string", "postalCode": "string", "phoneNumber": "string" } }, "eventId": "string", "customerId": "string", "nameSpace": "string", "reference": "string", "campaign": "string", "attributes": [ { "key": "string", "value": "string" } ] } ``` #### Response: 200 | Event | Type | Description | | ---------- | --------- | ------------------------------------ | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | tenantId | guid/uuid | A unique identifier for the tenant | | isExisting | bool | True if the eventId already existed | ``` { "eventId": "string", "customerId": "string", "tenantId": "string", "isExisting": true } ``` ## Create Transaction Represents an event notification that takes place in response to a customer’s completing a transaction such a card transaction, invoice or bill payment. The Transaction event is assessed against "Transaction" or "Spend" assessment rules and if matched fulfilment rules are applied. This processing of the event is **asynchronous**. ### POST ``` /api/v1/events/transactions ``` #### Request | Element | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------ | | transaction.source | decimal | Represents an amount related to the action | | transaction.total | decimal | Total transaction in Currency. Is the value used in Annual and Lifetime spend calculation | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | nameSpace | string | A namespace to represent the event, for example "Customer.Registration" | | reference | string | An external reference number | | campaign | string | An campaign identifier | | attributes\[] | List | A list of attributes | | attributes\[]key | string | Attribute Key | | attributes\[]value | string | Attribute Value | ``` { "transaction": { "source": "string", "total": 0 }, "eventId": "string", "customerId": "string", "nameSpace": "string", "reference": "string", "campaign": "string", "attributes": [ { "key": "string", "value": "string" } ] } ``` #### Response: 200 | Event | Type | Description | | ---------- | --------- | ------------------------------------ | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | tenantId | guid/uuid | A unique identifier for the tenant | | isExisting | bool | True if the eventId already existed | ``` { "eventId": "string", "customerId": "string", "tenantId": "string", "isExisting": true } ``` ## Create Redemption Represents an event notification that redeems a Customer’s points. No assessment rules can be configured or applied for this event, instead it automatically validates if the Customer account is not locked and has a sufficient points balance to complete the redemption. The validation (account status and balance check) is carried out synchronously and the current balance and points balance after the redemption is applied (the ‘pending balance’) are returned. The redemption is applied **asynchrously**. ### POST ``` /api/v1/events/redemptions ``` #### Request | Element | Type | Description | | ------------------ | --------- | ----------------------------------------------------------------------- | | action.amount | decimal | Represents an amount related to the action | | action.count | integer | Represent a counter related to the action | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | nameSpace | string | A namespace to represent the event, for example "Customer.Registration" | | reference | string | An external reference number | | campaign | string | An campaign identifier | | attributes\[] | List | A list of attributes | | attributes\[]key | string | Attribute Key | | attributes\[]value | string | Attribute Value | ``` { "redemption": { "externalReference": "string", "quantity": 0 }, "eventId": "string", "customerId": "string", "nameSpace": "string", "reference": "string", "campaign": "string", "attributes": [ { "key": "string", "value": "string" } ] } ``` #### Response: 200 | Event | Type | Description | | --------------- | --------- | ---------------------------------------------------------------- | | eventId | guid/uuid | A unique identifier for the event | | customerId | guid/uuid | A unique identifier for the customer | | tenantId | guid/uuid | A unique identifier for the tenant | | isExisting | bool | True if the eventId already existed | | startingBalance | int | The Customer Points Balance prior to redemption | | pendingBalance | int | The Customers Points Balance at the completion of the redemption | ``` { "startingBalance": 0, "pendingBalance": 0, "eventId": "string", "customerId": "string", "tenantId": "string", "isExisting": true } ```