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

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.

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
}