> ## Documentation Index
> Fetch the complete documentation index at: https://api.basedock.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Order Extra Fields: Definitions and API Usage

> Define and use custom extra fields on Base.com orders and returns. Read with getOrderExtraFields and write values using setOrderFields.

Extra fields are optional custom fields you define yourself in your Base account. They support multiple types — text, number, select, checkbox, radio, date, and file — and their values can be populated automatically by Base based on conditions such as order source, shipping method, destination country, or specific product, all configured through Automatic Actions.

## Why this is useful

A common scenario: your ERP uses different cost centers, invoicing series, or shipping methods depending on the destination country. Rather than replicating that entire conditional logic in your integration code, you can let Base evaluate the conditions and write the resulting value into an extra field. Your integration then simply reads that field.

When a rule changes later — say, a new carrier for a given country — you update it once in Base. No code deployment needed.

## Reading extra fields

<Steps>
  <Step title="Get field definitions and IDs">
    Call [`getOrderExtraFields`](https://api.baselinker.com/index.php?method=getOrderExtraFields) to retrieve all defined extra fields along with their IDs and types.
  </Step>

  <Step title="Include extra fields in your order requests">
    Add `include_custom_extra_fields: true` to your [`getOrders`](https://api.baselinker.com/index.php?method=getOrders) request.
  </Step>

  <Step title="Read the values from the response">
    The response includes a `custom_extra_fields` object keyed by field ID:

    ```json theme={null}
    "custom_extra_fields": {
      "135": "B2B",
      "172": "1646913115"
    }
    ```
  </Step>
</Steps>

<Note>
  For `file`-type extra fields, the value is an object rather than a plain string: `{"title": "...", "url": "..."}`, where `url` is a direct download link.
</Note>

## Writing extra fields

Extra field values are written using [`setOrderFields`](https://api.baselinker.com/index.php?method=setOrderFields) — the same method used to edit an order's address or notes. Only send the fields that actually changed; unchanged fields can be omitted from the request.

## Sample field definitions

The following shows what a `getOrderExtraFields` response looks like with a mix of field types:

```json theme={null}
{
  "extra_fields": [
    { "extra_field_id": 135, "name": "Client type", "editor_type": "radio", "options": ["B2B", "B2C"] },
    { "extra_field_id": 172, "name": "Shipping date deadline", "editor_type": "date" },
    { "extra_field_id": 196, "name": "Warranty Card", "editor_type": "file" }
  ]
}
```

## Extra fields on returns

Extra fields also exist for returns. Use [`getOrderReturnExtraFields`](https://api.baselinker.com/index.php?method=getOrderReturnExtraFields) to get their definitions — the reading and writing principles are exactly the same as for orders. See [Downloading Returns](/returns/downloading-returns) for full context.