Folders

Every order is contained in exactly one folder. Folders represent the stages that an order moves through in your store. A typical store has folders such as New, Prepared, Closed, and Canceled.

The folder_id field is used throughout this API, so it is worth understanding before you begin.

Retrieving Your Folder IDs

Folder IDs are specific to each store. Query the GET /store endpoint to retrieve them:

{
  "folders": {
    "21654": "New",
    "21655": "Prepared",
    "21656": "Closed",
    "21657": "Canceled"
  }
}

These should be retrieved once and cached. The IDs shown above belong to the example store and will not match your own.

Where Folders Are Used

When creating an order, omitting folder_id places the order in your first folder. Pass a value to place it elsewhere.

When searching, folder_id filters to a single folder, or to several when the IDs are separated by commas. The folder_name parameter performs the same filter using the folder's exact name.

To move existing orders, use the POST /move-orders endpoint rather than updating each order individually.

Please note that moving an order between folders triggers relevant folder change rules existing in your store. A folder change entry will also be added to the order history.

Folders and Updates

An update that omits folder_id leaves the order in its current folder. This is the one field that is not blanked when omitted, so that routine updates do not move orders unintentionally.