> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync dropdown options

> PUT /v1/payable-custom-fields/{fieldId}/options creates and updates a dropdown's options by your own externalId. Resending the same list changes nothing.

```
PUT /v1/payable-custom-fields/{fieldId}/options
```

**Scope:** `custom-fields:write`  ·  **Idempotency-Key:** optional

Creates and updates the options of a `DROPDOWN` or `MULTIPLE_CHOICE` field, keyed by your `externalId`. Use it to keep a dropdown in step with a list in your own system, such as your events.

**fieldId** `string` *required*

The field's `id` from [`GET /v1/payable-custom-fields`](https://docs.cleo-pay.com/api-reference/payable-custom-fields/list).

## Body

**options** `array` *required*

1 to 500 options. To sync more, split the list across several requests.

**options\[].externalId** `string` *required*

Your key for the option, for example your event id. 1 to 255 characters. Each `externalId` can appear once per request.

**options\[].label** `string` *required*

The text people choose from. Up to 100 characters, not blank. Leading and trailing spaces are removed, and runs of spaces become one. Two options can share a label.

**options\[].archived** `boolean`

`true` archives the option: it can no longer be chosen on new bills, and bills that already chose it keep it. `false` restores it. Leave it out to keep the option's archived state as it is.

Other keys inside an option are ignored, so you cannot set an option's `id` or `value`. An unknown top-level field answers `400 validation_error`.

## How options are matched

| You send | Result |
| - | - |
| An `externalId` the field does not have | A new option, with a new `id` and a `value` generated from the label. It is added after the existing options. |
| An `externalId` the field has | That option's `label` and archived state are updated. Its `id`, `value` and `externalId` do not change. |
| Nothing for an option | It is not changed. Options added in the Cleo web app (`externalId: null`) are never changed by a sync. |

Nothing is ever deleted. To retire an option, send it with `archived: true`.

A request that matches what is stored writes nothing, so you can resend your whole list on a schedule. Two syncs to the same field run one after the other, so neither loses the other's options.

## Example

```bash theme={null}
curl -X PUT https://api.stg.cleo-pay.com/v1/payable-custom-fields/8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e/options \
  --header "Authorization: Bearer $CLEO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 7d6c5b4a-3e2f-4a1b-9c8d-7e6f5a4b3c2d" \
  --data '{
    "options": [
      { "externalId": "evt-100", "label": "Spring Gala 2027" },
      { "externalId": "evt-101", "label": "Summer Festival 2027" },
      { "externalId": "evt-087", "label": "Winter Showcase 2026", "archived": true }
    ]
  }'
```

## Response

`200` with the [custom field](https://docs.cleo-pay.com/concepts/custom-fields.md#the-field-object) and its full `options` list: archived options, and options you did not send, included.

```json theme={null}
{
  "id": "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e",
  "label": "Event",
  "description": "The event this bill is for",
  "scope": "ROOT",
  "type": "DROPDOWN",
  "required": true,
  "options": [
    {
      "id": "e0f1a2b3-c4d5-4e6f-8a7b-9c0d1e2f3a4b",
      "value": "winter_showcase_2026",
      "label": "Winter Showcase 2026",
      "externalId": "evt-087",
      "archived": true,
      "archivedAt": "2026-10-27T16:05:11.000Z"
    },
    {
      "id": "2a7c9e1f-4b6d-4c8e-a0f2-3b5d7e9f1a2c",
      "value": "spring_gala_2027",
      "label": "Spring Gala 2027",
      "externalId": "evt-100",
      "archived": false,
      "archivedAt": null
    },
    {
      "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e",
      "value": "summer_festival_2027",
      "label": "Summer Festival 2027",
      "externalId": "evt-101",
      "archived": false,
      "archivedAt": null
    }
  ]
}
```

## Retrying

The sync is safe to repeat without a key: the same list a second time changes nothing. With an `Idempotency-Key`, a retry with the same body returns the first answer, and the same key with a different body answers `409 idempotency_conflict`. See [Idempotency](https://docs.cleo-pay.com/reference/idempotency.md).

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `validation_error` | `options` is missing, empty or longer than 500; an option has no `externalId` or `label`; a label is blank or longer than 100 characters; an `externalId` is longer than 255 characters; `archived` is not `true` or `false`; or the body has an unknown field. |
| 422 | `validation_error` | The field is not a `DROPDOWN` or `MULTIPLE_CHOICE` field, or an `externalId` appears more than once in the request. |
| 403 | `forbidden_scope` | The key lacks `custom-fields:write`, or its member cannot edit bills. |
| 404 | `not_found` | The field does not exist, belongs to another business, or was turned off or deleted. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was used for a different request, or that request is still running. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.