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 the package_description.
  • We don't validate the value of this field when POSTing, but it will be validated when syncing the uploaded file;
• 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 as cubic_decimeter), ft³ (use as cubic_foot), in³ (use as cubic_inch), m³ (use as cubic_meter), mm³ (use as cubic_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.