Order custom fields

Order custom fields let you define extra fields that appear inside each order's detail view for your team to fill in: internal reference numbers, special handling instructions, client PO numbers, or any tracking data your operations need. To manage them, go to Orders in the sidebar → click the table's ⋮ menu (in the last column header) → select Order Settings → click Custom Fields on the left. There is no gear icon: the ⋮ menu is the one.

Who can do what. Defining, changing, reordering, switching off and deleting fields needs a role that can manage store settings; a role that can only view store settings sees the list. Filling in a field's value on an order needs a role that can update orders.

Not the same as checkout custom fields. Checkout custom fields are buyer-facing questions asked during checkout (gift messages, delivery notes, etc.). Order custom fields are merchant-filled and show up in the order detail under Internal Fields.

Create a field

1. Go to Orders in the sidebar.
2. Click the table's ⋮ menu (in the last column header) and select Order Settings.
3. Click Custom Fields on the left side of the modal.
4. Click Add field at the bottom of the list. A row appears inline:

Click Add field again to save it.

Field types

An order field has seven types, and an image upload is not one of them. Text, Multiline text, Number, Checkbox, Dropdown, Date and Date and time are accepted. A field of type Image (a file the customer uploads, which checkout fields offer) cannot be created as an order field: it is refused, because an order field is filled in by your team and has nowhere to upload a file. If you need a photo or file on an order, put a link to it in a Text field.

Type the choices of a Dropdown when you create it. Pick Dropdown as the type and a Dropdown choices list appears in the same inline form. Each row has a Choice (the text your team sees) and an optional Saved value (what is stored on the order; leave it empty and the choice text is used). Use Add choice for more rows, the up and down arrows to reorder them, and the bin to remove one. The list is shown in that order, and the form will not save a Dropdown with no choices or with a repeated choice text or saved value. Spaces at the start and end are trimmed and empty rows are dropped. There is no limit on how many choices you add.

You cannot edit the choices of a Dropdown that already exists from the dashboard. The list of fields has no edit form, so to add, rename or remove a choice later, ask the AI assistant ("change the order field Priority to have the choices Low, Medium, High and Urgent"), which asks you to approve it first, or have your developer change the options through the API. A Dropdown you created earlier with no choices is fixed the same way.

A Dropdown only accepts one of its saved values, everywhere. The dashboard offers only your choices, and a value sent through the API, by an integration, by the AI assistant or from a connected AI tool must equal one of the saved values exactly (the choice text is not accepted, and capital letters count). Anything else is refused with a message that names the field and lists the allowed values. A Dropdown with no choices accepts no value at all, so add its choices first. Values already saved on past orders are never changed or re-checked, and saving an order's Internal Fields again with the same old value does not fail.

Date fields can be restricted. A Date field shows a calendar icon in the list. Click it to limit which dates can be chosen (earliest and latest date, blocked weekdays and dates) and to capture a time as well as a day. These are the same options as on checkout date fields.

Fill in values per order

Once you've defined fields, you can fill them in two ways:

1. In the order summary. Open the order's summary (the icon in the Summary column), scroll to the Internal Fields section, fill in the fields and click Save.
2. In the Orders table. Every active field is also a column in the Orders table that you can edit inline. The fields your customers filled in at checkout appear as columns too, hidden until you turn them on under Columns, and show what each customer entered.

Values are saved per order and are visible to any team member who opens that order. A Checkbox field saves yes or no, and a Number field refuses text.

Show a field in the order email to the customer

Turning on Public does not put a value in any email, and it does not make your storefront able to show it either: storefront order pages never receive internal field values. Order emails can print your custom fields, public or not, but no template does it out of the box: you add it once.

1. Go to Settings → Email and open the template you want, for example Order Confirmation or Order Completed.
2. In the editor, use the variable helper and insert orderCustomFields where you want the fields to appear.
3. Save. From then on, every order that has values shows them in that email.

Until you do this, a value saved on an order is stored correctly, visible to your team, and not shown to the customer in any email. If a customer says they never received a reference number or a code you know you saved, this is almost always why: check the template before anything else.

Ask the assistant to work with fields

You can also just ask: "put the courier reference ABC123 on order 1042". The assistant can set a value on an existing field, and will read back what it actually saved. It emails nobody when it does this. The value is recorded on the order, and reaches the customer only under the rules in the section above.

The assistant can also create a field and change one (rename it, change its help text, make it required or public, set a Dropdown's choices, or switch it off). Creating or changing a field changes your store's setup, so it asks you to approve it first. It cannot delete a field: do that in Order Settings → Custom Fields.

Fill a field automatically instead of by hand

You do not have to type values in yourself. If another system produces the value after the customer pays, a developer can have it written onto the order automatically. Typical cases: a licence key or activation code from a software supplier, a booking or reservation number, a warranty registration, a job number from a courier you are not connected to.

How it works, in plain terms: your developer subscribes to the order paid notification, calls the other company, gets the value back, and writes it into the field you created here. Then the order is marked completed, and the completion email goes out carrying the value, in your branding.

Give your developer these two things:

• The key of the field, which you can see in Orders → Order Settings → Custom Fields.
• This page for them: order custom fields in the API.

Two things worth knowing before you promise a customer anything:

• The email step above still applies. Automatic filling and showing it in the email are separate. If the template was never edited, the value arrives on the order and the customer still sees nothing.
• It is not instant, and it can fail. Most outside systems answer in seconds, some take minutes, and occasionally one errors. A well-built integration leaves the order not completed when that happens, so your list of paid orders that are not completed becomes your list of purchases needing a look.

Manage existing fields

In Orders → Order Settings → Custom Fields you can:

• Reorder. Drag the handle on a field up or down. The order is reflected in the order detail.
• Switch a field off or on. The switch on the row deactivates a field: it stops appearing on all orders, and the values already saved on past orders are kept. Switch it back on and they reappear.
• Delete with the trash icon. This removes the field itself, and you would have to create it again to use it. Values already saved on orders are not erased from those orders, but a value whose field was deleted is no longer printed in order emails. To stop using a field for now and keep it ready, switch it off instead.

What's next?

• Process an order to confirm payment and update order status.
• Add custom checkout fields to collect information from buyers during checkout.
• Custom fields (products) to add extra structured data to product records.