> For the complete documentation index, see [llms.txt](https://help.solink.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.solink.com/docs/install-connect-and-integrate/integrations/csv-formatting-guides/retail-format-guidelines.md). # Retail Format Guidelines 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 | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`--.csv`** | \* If you are splitting the files use \. This is often a store identifier. \* Can contain data for one or more stores as long as total group size is **below 50MB.** | | **`-.csv`** | \* If all data is in one file, the \ 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 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **\** | **Required**unique date stamp without separators\* Formats: \* YYYYMMDD (daily drops) \* YYYYMMDDTHHmm (multiple drops per day) \* Examples: \* 20240213-header.csv \* 20240213T1233-header.csv | | **\** | **Optional**Unique identifier representing the physical location of your store. \* Unique identifier usually represent the physical location of your store. Can be used to split larger file groups into smaller groups. \* Formats: \* Any Alphanumeric character \* A-Z, a-z, 0-9 \* Examples \* A203 \* store535 | | **\** | **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: * [Header File](https://github.com/SolinkCorp/help-centre-docs/tree/main/docs/.gitbook/assets/5dfb840d-20261001-STORE002-header.csv) * [Item File](https://github.com/SolinkCorp/help-centre-docs/tree/main/docs/.gitbook/assets/0c4b47eb-20261001-STORE002-item.csv) * [Payment File](https://github.com/SolinkCorp/help-centre-docs/tree/main/docs/.gitbook/assets/da4a9c3a-20261001-STORE002-payment.csv) ## 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. | | 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 | ✱ Required | String | 00510050BC3002 | 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](https://en.wikipedia.org/wiki/ISO_8601) datetime stringT required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found [here](https://en.wikipedia.org/wiki/Time_zone) If Z is used instead of +/- offset, time provided is in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) | | 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](https://en.wikipedia.org/wiki/ISO_8601) datetime stringT required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found [here](https://en.wikipedia.org/wiki/Time_zone) If Z is used instead of +/- offset, time provided is in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) | | status | ✱ Required | Picklist | “VOID”“REFUND”“SALE”"NO 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 | 101530 | 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.248.1115.52 | Total tax applied to the transaction | | customerId | Optional | String | 500525ece7c5f-6e5d-4136-83db-01a519a27f8b | Customer specific identifier | | receiptNumber | Optional | String | Db49aa0c-2019-4eab-b74b-e1d845d8f57a100010253 | 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. | | title | Optional | String | "New Line Activation""Dine In - Table 12""Device Upgrade - Trade In" | Custom title for the event card and video receipt in Solink. A value here replaces the title Solink calculates from status and the transaction total (for example, "$45.18 Sale"). Leave the cell blank to keep the calculated title, so you can override only the rows you want. Header file only. | ### 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 | 00510050BC3002 | 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](https://en.wikipedia.org/wiki/ISO_8601) datetime stringT required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found [here](https://en.wikipedia.org/wiki/Time_zone) If Z is used instead of +/- offset, time provided is in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) | | 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 | 1525.2 | The quantity of the item purchased. | | itemCode | Optional | String | B0CLHHS778B08SHV2R1Z | 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.984.55 | Price associated with the item. | | itemDiscount | Optional | Number | 15.5020 | 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 | 00510050BC3002 | 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 | 00510050BC3002 | 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 | 5025 | 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](https://en.wikipedia.org/wiki/ISO_8601) datetime stringT required on stamps to indicate timestamp Details after the + / - represent timezone values - full list of international Timezone values can be found [here](https://en.wikipedia.org/wiki/Time_zone) If Z is used instead of +/- offset, time provided is in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) | *** ## **Picklist Values** Below are the Picklist Values. ### Status (Required - Header File) | **Value** | **Description** | | --------- | ---------------------------------- | | sale | Standard completed sale | | void | Entire transaction voided | | refund | Refund transaction | | no sale | Till opened without a 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.** | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.solink.com/docs/install-connect-and-integrate/integrations/csv-formatting-guides/retail-format-guidelines.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.