JSON Upload

Upload a file

1. In Edit Logic, choose to upload a JSON file.
2. Write the file by hand from the example below, or copy the instructions in the upload dialog into an AI agent and let it write the file for you.
3. Upload the file. Its items and parameters load into the editor, where you can review and change them.
4. Save your changes. Your catalog is updated and your demo is regenerated.

Example

A small restaurant menu that uses every field on this page. Each section below explains one part of it.

{
  "items": [
    {
      "name": "pizza",
      "url": "https://www.example.com/menu/pizza",
      "image_url": "https://www.example.com/images/pizza.jpg",
      "metadata": { "sku": "PZ-001" },
      "parameters": [
        { "name": "calories", "values": [850, 1200] },
        { "name": "crust", "values": ["thin", "thick"] },
        {
          "name": "size",
          "values": ["small", "medium"],
          "when": [{ "parameter_name": "crust", "parameter_value": "thin" }]
        },
        {
          "name": "size",
          "values": ["medium", "large"],
          "when": [{ "parameter_name": "crust", "parameter_value": "thick" }]
        },
        {
          "name": "box_type",
          "values": ["reinforced"],
          "when": [
            { "parameter_name": "crust", "parameter_value": "thick" },
            { "parameter_name": "size", "parameter_value": "medium" }
          ]
        }
      ]
    },
    {
      "name": "pasta",
      "parameters": [{ "name": "sauce", "values": ["tomato", "cream"] }]
    }
  ],
  "top_level_parameters": [
    { "name": "order_type", "values": ["delivery", "pickup"] },
    { "name": "store", "values": [] }
  ],
  "custom_parameters": [
    { "name": "calories", "type": { "numeric": { "unit": "kcal" } } },
    { "name": "size", "option_order": "catalog", "multi_select": true },
    { "name": "sauce", "excluded_values": ["cream"] }
  ]
}

Top level

The file is one JSON object with these keys.

• Any key not listed on this page is rejected, so a typo such as "value" for "values" fails the upload instead of being ignored.
• A name used in top_level_parameters cannot also be used for a parameter inside an item.

Items

Each entry in items is one sellable item and the parameters that belong to it.

• No two items may share a name.
• url and image_url must be full addresses. A path on its own, such as /menu/pizza, is rejected.

Parameters

A parameter is one question a shopper answers, such as size or crust. Parameters go in an item's parameters list or in top_level_parameters, with the same fields in both.

• The name "item" is reserved and cannot be used.
• An empty values list marks a field whose options come from your app at runtime, such as stores, contacts or locations.
• The same parameter may appear more than once in one item when each copy has different conditions, such as a size list that depends on the crust.

Conditions

A condition makes a parameter appear only after another parameter has been answered with a given value. A parameter with several conditions appears only when all of them hold.

• List every ancestor condition, not just the nearest one. If box_type applies only when crust is thick and size is medium, its when lists both, even though size is its direct parent.
• A condition can only name a parameter from the same place: an item's parameters name parameters of that item, and top-level parameters name other top-level parameters.
• parameter_value is text, matched without regard to case. A numeric value is matched as written, so a value of 12.50 needs "12.50", not "12.5".
• parameter_value must be one of the values the named parameter lists, or "<ANY>". A parameter cannot name itself, and cannot name the same parameter twice.
• Write "<ANY>" exactly as shown: capital letters inside angle brackets.
• One parameter's conditions must form a single chain, at most 14 conditions long.

Parameter settings

custom_parameters changes how individual parameters behave, without changing the items. Each entry names a parameter and sets only the fields it includes.

• A field you leave out keeps its current setting, so a file without custom_parameters changes no settings.
• "excluded_values": [] clears the list. Once option_display or option_order is set, a file cannot return it to the default.
• An entry may name a parameter the file does not declare, such as one synced from Shopify. Settings belong to the product and outlast a new upload.
• To remove a parameter, leave it out of the items. custom_parameters has no field for deleting one.
• At most 500 entries, each naming a different parameter. excluded_values takes at most 500 values. A name or an excluded value is at most 256 bytes.

Parameter types

A type is an object with exactly one key, naming the kind of value. Numbers, dates and yes/no values each get options suited to them.

{ "type": { "string": {} } }
{ "type": { "numeric": { "unit": "min", "direction": "under" } } }
{ "type": { "date": { "date_format": "YYYY-MM-DD" } } }
{ "type": { "date_range": { "date_format": "YYYY-MM-DD", "separator": " to " } } }
{ "type": { "boolean": {} } }

• direction sets which way numeric ranges are cut. "under", the default, suits values where lower is better, such as a price: "under 10", "under 50", "at least 50". "over" suits values where higher is better, such as a rating.
• date_format is one of: YYYY-MM-DD, YYYY-MM, YYYY, DD/MM/YYYY, MM/DD/YYYY, DD-MM-YYYY, MM-DD-YYYY.
• separator is matched exactly as written, spaces included.