# Bulk file format

A JSON array of products, each in the same format as a single upsert. Include
`id` to target an existing product directly; otherwise `product_reference` is
matched.

The example shows a single-variant product with no options, and a two-variant
product where options are required.

```json
[
    {
        "product_reference": "abc123",
        "name": "Demo Product",
        "description": "A simple product with one variant, so no options are needed",
        "condition": "NEW",
        "delivery_type": "STANDARD_SHIPPING",
        "handling_time": 3,
        "quantity_per_lot": 1,
        "tags": "electronics,gadgets",
        "vendor": "ACME Inc.",
        "images": [
            { "src": "https://example.com/image1.jpg", "position": 1 }
        ],
        "variants": [
            {
                "variant_id_text": "ab1",
                "sku": "SKU-ABC123",
                "position": 1,
                "price": 199.99,
                "quantity": 5,
                "weight": 1.23
            }
        ]
    },
    {
        "id": 1234,
        "product_reference": "def456",
        "name": "Demo T-Shirt",
        "description": "Two variants, so each one needs at least one option",
        "condition": "NEW",
        "delivery_type": "STANDARD_SHIPPING",
        "images": [
            { "src": "https://example.com/shirt.jpg", "position": 1 }
        ],
        "variants": [
            {
                "variant_id_text": "shirt-small",
                "sku": "SHIRT-S",
                "position": 1,
                "price": 149.0,
                "quantity": 10,
                "weight": 0.3,
                "options": [
                    { "name": "Size", "value": "Small" }
                ]
            },
            {
                "variant_id_text": "shirt-large",
                "sku": "SHIRT-L",
                "position": 2,
                "price": 149.0,
                "quantity": 4,
                "weight": 0.35,
                "options": [
                    { "name": "Size", "value": "Large" }
                ]
            }
        ]
    }
]
```

`1234` is an example `id`. Use one from your own responses; an unknown `id`
stops the run.

## Checks applied to each product

The bulk run checks each product before storing it. A failed product is
skipped, its reason is added to `errors` on [Check bulk upload status](bulk_upload_status.md), and the
run continues.

| Error | Meaning |
| --- | --- |
| `product reference empty` | `product_reference` was missing or empty. |
| `NEW_ITEM is not in NEW,SECOND_HAND,REFURBISHED,OPEN_BOX` | Unrecognised `condition`. |
| `POSTAGE is not in STANDARD_SHIPPING,DIGITAL_DELIVERY,ALLOWS_COLLECTION,COLLECTION_ONLY` | Unrecognised `delivery_type`. |
| `handling time cannot be more than 15 days` | `handling_time` above 15. |
| `product with id:123 does not belong to given channel` | The `id` belongs to a product on another channel. |