| File Prefix | SALE |
| Current Version | V2 |
| Attribute | Format | Length | Required | Description | Example |
| sale_ref | Alphanumeric | 1-255 | Yes | Unique sale reference descriptor | 103495 |
| product_ref | Alphanumeric | 1-255 | Yes | Sale of given product | B01N53LF |
| quantity | Numeric | 1-7 | Yes | Quantity | 3 |
| price | Numeric | 1-10 | Yes | Unit Price of the sale | 599.90 |
| currency_code | ISO 4217 Must belong to our supported currencies | 3 | Yes | Currency for the sale | USD |
| created_at | Date and time ISO 8601 (UTC) | 19 | Yes | Date and time the sale occurred (in UTC) | 2022-01-17T10:15:18 |
| sku | Alphanumeric | 1-255 | No | SKU of product variant of the sale | B01N53LF |
| shopper_ref | Alphanumeric | 1-255 | Yes | Shopper who made the purchased | SHOPPER-1 |
| store_ref | Alphanumeric | 1-255 | No | Store where the sale happened | STORE-1 |
| sales_associate_ref | Alphanumeric | 1-255 | No | Sales associate who sold this line. Rows of one sale can name different associates — see Several associates on one sale | SALES_ASSOCIATE-1 |
Price
It is essential to communicate the sale price based on the unit price of each individual item, rather than the total price for all units. For example, if a sale comprises 2 identical belts, each priced at $20, the reporting should reflect the following:
Rows and lines
Each row is one line of a sale. The rows that share a sale_ref make up the sale, and its shopper, store, date and currency come from its first row. Sending a sale_ref again replaces its lines.
Rows with the same product_ref, sku and price, whose quantities have the same sign, are added together into one line. Two rows for the same $20 belt, each with quantity 1, become one line with quantity 2 — the same as sending a single row with quantity 2. Rows that differ in sku or price, or in the sign of quantity (in an exchange, a return beside the re-purchase), stay separate lines.
Several associates on one sale
Rows of the same sale can name different sales_associate_ref values, and rows naming different associates are never added together. Each associate is credited with the revenue and units of the lines they sold, and the sale counts toward each associate who sold something on it. On an exchange, the returned lines reduce each seller’s credit in proportion to their share, and an associate who appears only on returned lines isn’t credited. The sale itself is attributed to the associate with the largest share; on a tie, to the one whose row comes first.
A row with no sales_associate_ref, or one that matches no sales associate, is credited to the associate on the sale’s first row — or, when that one doesn’t match either, to the associate the sale is attributed to.
This applies to accounts created on or after October 7, 2026, and to earlier accounts where BSPK has turned it on. On other accounts, the whole sale is credited to the associate on its first row, and rows that differ only in sales_associate_ref are added together. Ask your BSPK contact to turn it on for an earlier account; sales imported before it was turned on keep their credit until they are sent again.
