Assortment Files
The assortment file is the collection of items, packages and item prices that gets posted to the create assortment file endpoint.
File Structure
This endpoint expects a JSON file with the following structure:
[
{
"third_party_id": string, --> required
"shared_id": string,
"supplier_outlet_id": string,
"brand": string,
"name": string, --> required
"description": string,
"package_type": string,
"price_type_code": integer, --> required (0: per package; 1: per unit)
"orderable": boolean, --> defaults to true
"gtin": string,
"price": decimal, --> required
"package_description": { --> required if "package_description_str" is missing
"quantity": decimal, --> required
"gtin":string,
"package": {
"quantity": decimal,
"unit_name": string --> required at lower level
}
},
"package_description_str": string --> required if "package_description" is missing
},
{...}
]
The package_description
attribute has a recursive nature. Its package
can be a nested structure that contains other packages. This is also a viable representation:
{
"package_description": {
"quantity": decimal, --> required
"gtin":string,
"package": { --> required for nested packages
"quantity": decimal,
"package": {
"quantity": decimal,
"package: {
....
"unit_name": string --> required at the lowest level
}
}
}
}
}
- third_party_id: The package's unique identifier (REQUIRED);
- shared_id: An ID that identifies the article that the package belongs to (or an identifier shared between packages);
- supplier_outlet_id: The ID of the supplier distribution centre associated with the assortment;
- brand: The article's brand;
- name: The name of the article (REQUIRED);
- description: Any extra information about the package;
- package_type: The type of package (if it's a box, case or ...)
- price_type_code: If the package is billed by its unit (1) or by the whole package (0);
- orderable: True, if the package can be ordered (default). False, otherwise;
- gtin: The article's GTIN/EAN/UPC code;
- Use this field only if you're sending the package structure with the
package_description_str
field (see below). Otherwise, send it directly within thepackage_description
. - We don't validate the value of this field when POSTing, but it will be validated when syncing the uploaded file;
- Use this field only if you're sending the package structure with the
- price: The price of the article;
- package_description: How the package is structured. You can provide this value in two ways (and one of the two is REQUIRED).
The Package Description
The package_description
field is critical when sending integrated assortment items. Its completeness will be validated, as we rely on this information to ensure accurate pricing and measurements. For instance, we will not allow items to be sent with no indication of weight, volume, or quantity.
The package description can be specified in the following ways:
- As a nested JSON (using the
package_description
attribute):
{
"package_description": {
"quantity": 2.0,
"gtin": "26989625952452",
"package": {
"quantity": 3.0,
"package": {
"quantity": 100.0,
"unit_name": "g"
}
}
}
}
- As a string (using the
package_description_str
attribute):
{"package_description_str": "2 x 3 x 100 g"}
Please, note that if you plan to use this field, you must be consistent with the "package multipliers" format. That is to say that if you use the format above, we expect all files in all assortments to follow the same format, and not something like "2/3/100g". Although both are supported, the files must keep consistent with the chosen format.
In case of doubt, reach out to us.
A Real Example
Consider a package that contains a box of wine bottles (750 ml), with 6 bottles in total. We'll explore the package_description
field in more detail, assuming that the individual bottle can either be ordered separately or not.
Bottles ARE individually orderable
It is possible to order a single bottle.
Since you have two orderable packages, we need two items in the package_description
array. Each item will have the same shared_id
but unique third_party_ids
:
[
{
"third_party_id": "CS123456",
"shared_id": "123456",
"package_description": {
"quantity": 6.0,
"package": {
"quantity": 750.0,
"unit_name": "ml"
},
"gtin": "2698962595245"
},
...
},
{
"third_party_id": "EA123456",
"shared_id": "123456",
"package_description": {
"quantity": 750.0,
"unit_name": "ml",
"gtin": "6820540261525"
},
...
},
]
This will generate two orderable packages: one that represents the whole box, and one that represents the bottles.
Bottles ARE NOT individually orderable
It is not possible to order a single bottle separately.
Without nested packages, you should provide only one item:
[
{
"third_party_id": "123456",
"package_description": {
"quantity": 6.0,
"package": {
"quantity": 750.0,
"unit_name": "ml"
},
"gtin": "2698962595245"
},
...
}
]
There's no need to provide a value for the shared_id
attribute, either. This will generate a package for the whole box.
Supported Units
- For mass: μg, mg, g, kg, tonne, oz, lb, metric ton, short ton, long ton
- For volume: cm³ (use as
cubic_centimeter
), dm³ (use ascubic_decimeter
), ft³ (use ascubic_foot
), in³ (use ascubic_inch
), m³ (use ascubic_meter
), mm³ (use ascubic_milliliter
), cup (UK), cup (US), fl oz (UK), fl oz (US), gal (UK), gal (US), l, pt (UK), pt (US), qt (UK), qt (UK), tbsp (UK), tbsp (UK), tsp (UK), tsp (UK), DZ, #10 - Pieces: piece
Units that cannot be interpreted (not included in this list) will default to piece
.
Updated about 1 month ago