Use this article when you're mapping your data feeds to Toolio. It answers common questions about core attributes, grouped by the feed they belong to. For the full list of fields in each feed, see Import Templates.
Product Feed
Toolio organizes your catalog into three levels: product, choice, and variant. Your Product feed has one row per variant, and every row carries all three IDs so Toolio knows how your SKUs roll up.
Level | Attribute | Description | Example Fields |
Product |
| The base design, regardless of color or size. Every choice and variant of the style shares the same | Style, Item, Model |
Choice |
| One version of the style a customer can choose, usually a colorway. Every variant of the choice shares the same | Style-Color |
Variant |
| The single sellable unit, usually one size of a choice. Each variant has its own unique | Style-Color-Size, UPC, SKU |
Example: a crew-neck tee
product_id | choice_id | variant_id | Color | Size |
TEE100 | TEE100-BLK | TEE100-BLK-S | Black | S |
TEE100 | TEE100-BLK | TEE100-BLK-M | Black | M |
TEE100 | TEE100-WHT | TEE100-WHT-S | White | S |
TEE100 | TEE100-WHT | TEE100-WHT-M | White | M |
That's one product (TEE100), two choices (TEE100-BLK and TEE100-WHT), and four variants.
What should I use for product_id?
Use your style number, or whatever ID groups every color and size of one design. If your catalog has no style number, a parent field like a Shopify product ID or NetSuite parent item usually works.
What is a choice and what should I use for choice_id?
A choice is the level your team plans and buys at, usually the style-color. Each choice is one line in the Assortment Plan, and Toolio uses size curves to split each choice's quantities into sizes when it creates purchase orders.
For choice_id, most brands combine the style number and color code, e.g. TEE100-BLK. If style-color doesn't match how your team plans and buys, your Toolio team can help you define it.
What should I use for variant_id?
Use a unique ID for each sellable unit, usually the SKU from your ERP or ecom platform. Your Sale, Inventory, Purchase Order, and Receipt feeds all match back to the Product feed on variant_id, so the value must be identical in every feed. Use identifiers that won't change over time.
What should I send for size if my products aren't sized?
Size is required in Toolio. If your products aren't sized, like household goods, accessories, or cosmetics, work with your Implementation Specialist to set a default size value, like OS or One Size.
How do I send two-dimensional sizes, like waist/length?
Combine them into one Size value, e.g. waist 36 and length 32 becomes 36-32. Use the same concatenation logic everywhere, since 36-32 and 36x32 would be treated as different sizes.
You can send a ready-made Size field, or send both fields and have Toolio combine them using an import mapper. Work with your Implementation Specialist to define the concatenation logic you want.
Sale Feed
What should I use for sale_id?
Use a unique ID you can rebuild the same way every time you send the row. When you resend a sale_id, Toolio updates that sale line instead of creating a duplicate. Common options:
Transaction-level sales: a line item ID (e.g. Shopify
line_item_id), or{order_id}_{variant_id}Sales aggregated by day:
{date}_{location}_{variant_id}, e.g.2026-10-01_1234_999999
What should I send for sales_retail?
Sales Retail is the price the customer actually paid after markdowns and discounts. Gross Sales Ticket, the full-price (MSRP) value, is calculated in Toolio for you:
Gross Sales Ticket = Sales Retail + Markdown + Discount
For example, a $100 tee marked down by $10, with a $20 discount code applied at checkout:
Field | Value | Send it? |
| $70 | Yes |
| $10 | Yes |
| $20 | Yes |
Gross Sales Ticket | $100 | No, Toolio calculates it |
❗ Always send Markdown and Discount as positive values. Negative values would understate Gross Sales Ticket.
Should returns_retail include markdowns and discounts?
Yes. Returns Retail is the amount refunded to the customer, after any markdowns and discounts from the original sale. In the example above, if the customer returns the tee, Returns Retail is $70, not $100.
Location Feed
Should location be a name or an identifier?
Use a unique identifier, like a store number. Store names change over time, and a changed value splits that location's history.
To show a readable store name in Toolio instead of the location ID, use the location_name field. You can send it on your Location import, or edit it directly in Settings > Organization Settings > Locations. See Location Management.