Order custom fields

Add internal tracking fields to every order, such as reference numbers, handling notes, client POs, or any data your team needs to record per order.

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 → open the Settings (⚙ gear) menu in the top-right → select Order Settings → click Custom Fields on the left.

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

Go to Orders in the sidebar.
Open the Settings (⚙ gear) menu in the top-right toolbar and select Order Settings.
Click Custom Fields on the left side of the modal.
Click Add Field at the bottom of the list. A row appears inline:

Setting	What it does
Name	The label shown in the order detail (e.g. `Internal reference`, `Client PO`).
Key	Auto-generated from the name in `snake_case`. Cannot be changed after creation.
Type	The input type (see the table below).
Required	A toggle. When on, the field must be filled before saving.
Public	A toggle. When on, the value is visible to the customer (e.g. on the order confirmation). Leave off for internal-only fields.

Click Add to save the field.

Field types

Type	Use it for
Text	Short strings: reference numbers, notes, client name
Long Text	Multi-line text: detailed handling instructions, remarks
Number	Numeric values: quantity adjustments, floor numbers
Yes/No	Toggles such as "Rush order", "Fragile", "VIP customer"
Select	Choose one from a preset list, for example Priority: Low / Medium / High
Date	Date picker for a promised ship date or follow-up date

Fill in values per order

Once you've defined fields, they appear in every order's detail view:

Click any order in the Orders list to open it.
Scroll to the Internal Fields section.
Fill in the fields for that order.
Click Save.

Values are saved per order and are visible to any team member who opens that order.

Show a field in the order email to the customer

Turning on Public makes a value visible to the customer on their order page. It does not put it in the emails. Order emails can print your custom fields, but no template does it out of the box: you add it once.

Go to Settings → Email and open the template you want, for example Order Confirmation or Order Completed.
In the editor, use the variable helper and insert orderCustomFields where you want the fields to appear.
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 fill in a field

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 cannot create a new field, so if the one you name does not exist it will tell you which ones do and send you to the settings page above.

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.

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 fields up or down. The order is reflected in the order detail.
Active / Inactive toggle. Inactive fields stop appearing on all orders (existing saved values are preserved).
Delete removes the field definition. Saved values on past orders are also removed.

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.

On this page