This document defines the Retail CSV format for integrating point-of-sale (POS) transaction data into Solink. Data is split across three CSV files (header, item, payment) that are linked together by transactionId, storeId, and registerId.

File Details

When sending data for a Solink integration, please ensure files are separated as follows:

1 file for headers
1 file for items
1 file for payments

File Naming Format

File Name breakdown	Details
`<datestamp>-<storeId>-<fileType>.csv`	If you are splitting the files out by store, use <storeId>. Can contain data for one or more stores as long as total group size is below 50MB
`<datestamp>-<fileType>.csv`	If all stores are in one file, the <storeId> can be omitted. Can contain data for one or more stores as long as total group size is below 50MB

File Part Details

File name part	Additional details
<datestamp>	Required unique date stamp without separators Formats: YYYYMMDD (daily drops) YYYYMMDDTHHmm (multiple drops per day) Examples: 20240213-header.csv 20240213T1233-header.csv
<storeId>	Optional Unique identifier representing the physical location of your store. used if files contain the data for a single location. Identifier is tied to your configuration and should not change Formats: Any Alphanumeric character A-Z, a-z, 0-9 Examples A203 store535
<fileType>	Required Indicates what data can be found within the files. Must be one of the following: Header Item Payment

Samples

Refer to the examples and tables below for information on formatting CSV if your business operates in retail industries:

Examples of data files from the retail industry:

File Formats

Below are the Header File, Item File and Payment File formats.

Header File Format

Column Name	Required *	Data Type	Examples	Purpose
dataType	✱ Required	Picklist	‘retail’	Defines what Schema will be used by Solink when processing your data.
storeId	✱ Required	String	005 10050B C3002	Unique identifier representing the site / store the information is sourced from
registerId	✱ Required	String	001, 5023, 91591cc4-9b4b-4f26-bcb2-f6cbdd18c822	Unique identifier representing the register that generated the data within the store.
registerName	Optional	String	“Register 1” “Kitchen Till” “Lane 1 register”	Friendly name of register - name of the register. Useful when the registerId is a GUID / number and not easily discernible by humans
storeName	✱ Required	String	“Clover Ridge” “Valley Farm” “Downtown 5”	String that provides a unique human readable description of the store
startTime	✱ Required	Date/Time	YYYY-MM-DDTHH:MM:SS.sss±HH:MM “2024-06-15T06:15:00.000-06:00” YYYY-MM-DDTHH:MM:SS.sssZ “2024-06-15T06:15:00.000Z”	Date/Time Transaction started ISO-8601 datetime string T required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found here If Z is used instead of +/- offset, time provided is in UTC
endTime	Optional	Date/Time	YYYY-MM-DDTHH:MM:SS.sss±HH:MM “2024-06-15T06:15:00.000-06:00” YYYY-MM-DDTHH:MM:SS.sssZ “2024-06-15T06:15:00.000Z”	Date/Time Transaction ended ISO-8601 datetime string T required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found here If Z is used instead of +/- offset, time provided is in UTC
status	✱ Required	Picklist	“VOID” “REFUND” “SALE”	Transaction level status. Must be one of the noted values listed in the examples section
employeeName	Optional	String	“John Smith” “Jane Smith”	employee who generated the data or transaction.
employeeID	Optional	String	“502” "80125F”	String representing the employee id in the system that generated the data or transaction.
transactionDiscount	Optional	Number	10 15 30	Total Transaction level discounts applied. These are separate from the item level discounts that may have been applied. For example, the POS calculates a veterans discount after all item level discounts have been applied. The discount will appear in this column.
transactionDiscountReason	Optional	String	“Customer Service \| Veterans Discount” “Upsell opportunity” “Coupon \| Loyalty”	String of '\|' separated list of transaction discount reasons. WIll be appended to Video receipt
transactionTax	Optional	Number	5.24 8.11 15.52	Total tax applied to the transaction
customerId	Optional	String	50052 5ece7c5f-6e5d-4136-83db-01a519a27f8b	Customer specific identifier
receiptNumber	Optional	String	Db49aa0c-2019-4eab-b74b-e1d845d8f57a 100010253	POS receipt number. Often used to match the transaction to the receipt generated in store.
notes	Optional	String	“Flag for review” “Void - Customer needed to make change” “Refund - Customer wanted refund on TX because they were unsatisfied with service”	Notes associated with the transaction. Will be indexed and searchable within Solink
salesAssociateID	Optional	String	“502” "80125F”	The ID of the sales associate.
salesAssociateName	Optional	String	“John Smith” “Jane Smith”	The Name of the sales associate.
revenueCenter	Optional	String	“Sports” “Grocery” “Electrionics” “Cosmetics”	Identifies the department or service area where the transaction occurred. In retail, this may be a store department.

Item File Format

Column Name	Required *	Data Type	Examples	Purpose
transactionId	✱ Required	String	10002424 “10002424” 43e27ef4-67a0-40ea-9655-8ab69f7e4bae “43e27ef4-67a0-40ea-9655-8ab69f7e4bae”	Unique identifier for the transaction. Serves as primary key across Header, Item and Payment files
storeId	Optional	String	005 10050B C3002	Unique identifier representing the site / store the information is sourced from
registerId	Optional	String	001, 5023, 91591cc4-9b4b-4f26-bcb2-f6cbdd18c822	Unique identifier representing the register that generated the data within the store.
itemTime	Optional	Date/Time	YYYY-MM-DDTHH:MM:SS.sss±HH:MM “2024-06-15T06:15:00.000-06:00” YYYY-MM-DDTHH:MM:SS.sssZ “2024-06-15T06:15:00.000Z”	Date/Time Item added to transaction If used, must be contained within startTime and endTime noted in header. ISO-8601 datetime string T required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found here If Z is used instead of +/- offset, time provided is in UTC
itemStatus	✱ Required	Picklist	‘Void’ ‘Return’ ‘Sale’ ‘Override’ 'Gratuity'	Indicates specific status of item on transaction. Must be one of the identified values noted in examples
itemStatusReason	Optional	String	“Customer no longer wanted the item” “Adusting price to match listed sale price”	Descriptive comment as to the reason this status was assigned.
quantity	✱ Required	Number	1 5 2 5.2	The quantity of the item purchased.
itemCode	Optional	String	B0CLHHS778 B08SHV2R1Z	The unique code or SKU that identifies the item in the POS service or data warehouse
itemDescription	✱ Required	String	“Levis 501 \| 34 w x 40 L \| Stone washed \| Boot cut” .	Descriptive comment associated with the item. May consist of a ‘\|' separated collection of modifiers. The additional modifiers will appear below the line item entry in the receipt.
unitPrice	✱ Required	Number	5.98 4.55	Price associated with the item.
itemDiscount	Optional	Number	15.50 20	Total discounts to be applied per item.
itemDiscountReason	Optional	String	“Coupon 2For1 ($5) \| Outdoor living promo ($10) \| “Student ($0.50)”	\|' separated list of transaction discount reasons. May optionally include a discount contribution.
originalTransactionId	Optional	String	10002424 “10002424” 43e27ef4-67a0-40ea-9655-8ab69f7e4bae “43e27ef4-67a0-40ea-9655-8ab69f7e4bae”	if the item is being returned, the original Transaction ID of the purchase
originalBusinessDate	Optional	String	YYYY-MM-DD	if the item is being returned, the original Business Date of the purchase
originalStoreId	Optional	String	005 10050B C3002	if the item is being returned, the original Store ID of the purchase was made
originalRegisterId	Optional	String	001, 5023, 91591cc4-9b4b-4f26-bcb2-f6cbdd18c822	if the item is being returned, the original Register ID where the purchase was processed
itemCategory	Optional	String	clothing, accessories, food, service	The category of the item

Payment File Format

Column Name	Required *	Data Type	Examples	Purpose
transactionId	✱ Required	String	10002424 “10002424” 43e27ef4-67a0-40ea-9655-8ab69f7e4bae “43e27ef4-67a0-40ea-9655-8ab69f7e4bae”	String that uniquely identifies the transaction within the sender’s data warehouse.
storeId	Optional	String	005 10050B C3002	String that uniquely identifies the store that generated the data.
registerId	Optional	String	001, 5023, 91591cc4-9b4b-4f26-bcb2-f6cbdd18c822	String that uniquely identifies the pos register that generated the data within the store
tenderType	✱ Required	String	‘Credit VISA’ ‘Credit AMEX’ ‘Credit MasterCard’ ‘Debit’ ‘Cash’ ‘Cheque’ ‘Gift Card’ ‘Loyalty’	Tender accepted for the transaction. Can be any relevant value. Providing the issuer is a useful datapoint that can be included as well.
totalPaymentTendered	✱ Required	Number	50 25	The total amount tendered of the specified tenderType
changeDue	Optional	Number	23.2	Required for Cash transactions where the totalPaymentTendered > total purchase amount
customerId	Optional	String	244402234	A redacted or otherwise PII compliant customer identifier
cardLastFour	Optional	String	4532	The last four digits of the card are used for payments.
paymentStatus	Optional	String	“Approved \| Swiped \| ”	\|' separated payment status fields to qualify the payment tendered.
paymentTime	Optional	Date/Time	YYYY-MM-DDTHH:MM:SS.sss±HH:MM “2024-06-15T06:15:00.000-06:00” YYYY-MM-DDTHH:MM:SS.sssZ “2024-06-15T06:15:00.000Z”	Date/Time that payment was tendered. If used, must be contained within startTime and endTime noted in the header. ISO-8601 datetime string T required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found here If Z is used instead of +/- offset, time provided is in UTC

Picklist Values

Below are the Picklist Values.

Status (Required - Header File)

Value	Description
sale	Standard completed sale
void	Entire transaction voided
refund	Refund transaction

Item Status (Required - Item File)

Value	Description
SALE	Standard sale item. Unit price absolute value is used.
VOID	Voided item. Unit price absolute value is used; item type set to VOID.
RETURN	Returned item. Unit price absolute value is used; item type set to RETURN.
GRATUITY	Tip/gratuity line item.

Common Issues

Scenario	Description
Returns / exchange handling	When sending returns data to Solink - Quantity and Amount in the item file should be positive always
Refund handling	When returning tender to the customer the TransactionTax (Header) should be a negative number along with totalPaymentTendered(Payment)
Amount Mismatches	The sum of line items (Unit Price + Tax - Discount) does not equal the total payment tendered, Common drivers of this are due to unreported tax or discounts.
Orphaned Records	Missing corresponding Payment / Item / Header transactionIDs between files can result in records missing details or missing entirely
Duplicate Records	Duplicated payment / item records will result in double payments / additional items within Transaction. Duplicated headers will not result in duplicated transactions, but will overwrite older records with newer details