Retail Transaction Schema

Solink tags video to retail transactions based on a unique place and time pairing. Time is absolute and must adhere to the convention defined here.

Required Object Fields

Field	Type	Description
`dataSourceId`	String	A unique identifier representing the source of the transaction data, typically a point-of-sale (POS) register, kiosk, or fuel pump within the retail environment. This ID helps differentiate where each transaction originated within the store.
`dataType`	String	Must be set to "retail" to specify which data type the current event is.
`endTime`	Number / String	End time of the transaction in either Unix time format milliseconds or ISO-8601 compliant format.
`items`	Array	The list of items, actions or events processed in the transaction.
`schemaVersion`	String	Must be set to "1" to specify which version of the schema is being used for this event (e.g. "1", "2", etc).
`siteExternalId`	String	Unique location identifier within the customer's set of locations.
`startTime`	Number / String	Start time of the transaction in either Unix time format milliseconds or ISO-8601 compliant format.
`status`	String	Describes the type of transaction. For example: "SALE" or "VOID". Supported Enum values: 'sale', 'void', 'refund', 'return', 'discount', 'exchange', 'cancel', 'no sale', 'post void', 'other', 'rebate'.
`transactionId`	String	Unique ID which identifies the transaction in the originating POS software. If transaction numbers can repeat or roll over, it’s recommended to append a date/time suffix (e.g., YYYYMMDDHH) to ensure uniqueness over time. WARNING: Transactions sharing the same transactionId will be upserted, meaning the latest data will overwrite the previous record.

Optional Object Fields

Field	Type	Description
`customerId`	String	The unique id to identify the customer being served.
`employeeId`	String	Unique employee id to identify the employee processing the transaction.
`employeeName`	String	The name of the employee processing the transaction.
`notes`	String	Additional notes or comments about the event.
`revenueCenter`	String	Identifies the department or service area within a location where the transaction occurred. In retail, this may be a store department (e.g., electronics or cosmetics). In restaurants, it may be a dining area or channel (e.g., bar, patio, takeout, drive-thru). Businesses use revenue centers to track and compare performance across different areas.
`salesAssociateId`	String	A unique identifier for the sales/floor associate who assisted the customer and may be eligible for commission on this transaction.
`salesAssociateName`	String	The human-readable full name of the sales/floor associate who assisted the customer and may be eligible for commission.

Required Item Object Fields

Field	Type	Description
`description`	String	Description of the item.
`quantity`	Number	Quantity of the item.
`time`	Number \| String	Start time of the transaction in either Unix time format milliseconds or ISO-8601 compliant format.
`type`	String	May be one of the following allowed values: "SALE": Item sold at list price. "MODIFIER": Item modified with/without corresponding price modifications. "SALE_OVERRIDE": Item sale price was overridden by the employee. Final override price is recorded in unitPrice. "OVERRIDE_MODIFIER": Override item modified with/without corresponding price modifications. "DISCOUNT": A discount was applied to the transaction. "DISCOUNT_MODIFIER": The discount was modified with/without corresponding price modifications. "RETURN": Item was returned. "RETURN_MODIFIER": Returned item modified with/without corresponding price modifications. "RETURN_DISCOUNT": Returned item discount. "RETURN_DISCOUNT_MODIFIER": Returned item discount modifier. "PAYMENT": Payment applied to the transaction. "REFUND": Refund payment previously applied to the transaction. "CHANGE_DUE": Change due to the customer for a cash payment tendered > transaction total. "TAX": Tax to be applied to the transaction. "REFUND_TAX": Refund tax previously applied to the transaction. "OTHER_CHARGES": Other charges associated with the transaction. "REFUND_OTHER_CHARGES": Refund other charges previously applied to the transaction. "GRATUITY": Gratuity offered by the customer. "VOID": Item entry voided. "VOID_MODIFIER": Item modifier entry voided/cancelled. "VOID_DISCOUNT": Item discount entry voided/cancelled. "VOID_RETURN": Item returned entry voided/cancelled. "VOID_PAYMENT": Payment entry voided/cancelled. "VOID_CHANGE_DUE": Change due entry voided/cancelled. "VOID_REFUND": Refund payment voided/cancelled. "DISCOUNT_ITEM": Discount applied to an item (item-level). Note: Differs from DISCOUNT which applies to the whole transaction (transaction-level discount). "RETURN_DISCOUNT_ITEM": Returned item discount. Note: Differs from RETURN_DISCOUNT which applies to a returned transaction. "VOID_DISCOUNT_ITEM": Item discount entry voided/cancelled. Note: Differs from VOID_DISCOUNT which applies at the transaction level. "ROUNDING_AMOUNT": Rounding amount/adjustments made. "PREPAYMENT": Prepaid items — customer pays before receiving it. "PREPAYMENT_ITEM": Payment made before receiving the items. "REBATE": Rebate item. "RETURN_REBATE": Returned rebate item. "VOID_REBATE": Rebate entry voided/canceled.
`unitPrice`	Number	Per unit price of the item.

Optional Item Object Fields

Field	Type	Description
`cardNumberLast4`	String	For credit/debit/gift card payment/refund/void. Last four digits of the card number.
`category`	String	Used to track Item Category
`sku`	String	SKU or other unique item identifier.

JSON Example

{
  "dataType": "retail",
  "schemaVersion": "1",
  "startTime": 1557943653649,
  "endTime": 1557943678649,
  "siteExternalId": "123",
  "dataSourceId": "1",
  "transactionId": "93688",
  "employeeId": "27",
  "employeeName": "MICHELLE",
  "status": "SALE",
  "customerId": "5hs86ac0-34b4-11ea-93d3-21eb8a2fs123",

  "items": [
    {
      "type": "sale",
      "quantity": 1.0,
      "description": "767062 - 1L COLA",
      "unitPrice": 2.29,
      "time": 1557943655649
    },
    {
      "type": "tax",
      "description": "PST",
      "unitPrice": 0.32,
      "time": 1557943678649
    },
    {
      "type": "payment",
      "description": "Credit",
      "unitPrice": 2.61,
      "cardNumberLast4": "1234",
			"time": 1557943678649
    },
    {
      "type": "change_due",
      "description": "Change",
      "unitPrice": 0.0,
      "time": 1557943678649
    }
  ]
}