> ## 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 a dropdown and group bills

> Keep a bill dropdown, such as an event list, in step with your own system, then read each bill's choice and list the bills for one event.

This guide keeps a business's **Event** dropdown in step with the events in your own system, so every bill names an event you know. You then read each bill's event and group bills by it. The same steps work for any list: projects, jobs, cost centers.

You need a key with `custom-fields:read` and `custom-fields:write` to sync, `payables:read` to read bills, and `payables:write` to create or submit bills with an event.

**1. Create the field in the Cleo web app**

An admin adds an **Invoice-level** question of type **Dropdown**, named "Event", under **Settings** > **Invoices** > **Custom Questions**. Leave it optional for now. The API cannot create fields.

The web app saves a dropdown only with at least one option. That first option has no `externalId`, so a sync never changes it. If it is not one of your events, archive it in the web app after your first sync.

**2. Find the field id**

Call `GET /v1/payable-custom-fields` and find the field with `"label": "Event"`, `"scope": "ROOT"` and `"type": "DROPDOWN"`. Store its `id`. It does not change.

**3. Push your events**

Send your events to `PUT /v1/payable-custom-fields/{fieldId}/options`, with your event id as `externalId` and the event name as `label`.

**4. Send the event on bills you create**

When your integration creates or submits a bill, send the event's `externalId` as the field's answer in `customFields`.

**5. Mark the field required**

Call `GET /v1/payable-custom-fields` and check that the field lists your events. Then an admin marks it required, so the Cleo web app asks for an event when a vendor sends a bill through Cleo or someone at the business enters one. Before your events are synced, a required field makes vendors pick an option that is not one of your events, or refuses their bills when it has no options.

A required field applies to the API too. Once it is required, a bill you create with `submit: true`, and every bill you submit, must name an event. That is why your integration sends the event first.

**6. Read and group bills**

Read each bill's answer by the field id, and map its `externalId` back to your event. Or list one event's bills with the `customFieldId` filter.

## Push your events

```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" \
  --data '{
    "options": [
      { "externalId": "evt-100", "label": "Spring Gala 2027" },
      { "externalId": "evt-101", "label": "Summer Festival 2027" }
    ]
  }'
```

Run the sync on a schedule, or whenever an event changes. Each run can send your whole list:

* **A new event** gets a new option.
* **A renamed event** keeps its option. Send the same `externalId` with the new `label`. Bills that already chose it show the new name.
* **A finished or cancelled event** is archived. Send it with `"archived": true`. Vendors can no longer pick it, and its bills keep it.
* **A restored event** is sent with `"archived": false`.
* **An unchanged event** is not written again, so resending the whole list is cheap and safe.

Events you leave out of a request are not changed, and no option is ever deleted. Send up to 500 options per request. For a longer list, send it in several requests.

Labels do not need to be unique. Two events with the same name stay separate options because their `externalId` values differ.

## Send the event on a bill

Answer the Event field by its `fieldId`, with your event id as `value`. Cleo matches it against each option's `id`, then `externalId`, then `value`.

```bash theme={null}
curl -X POST https://api.stg.cleo-pay.com/v1/payables \
  --header "Authorization: Bearer $CLEO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 9c2e4a6b-1d3f-4e5a-8b7c-0d1e2f3a4b5c" \
  --data '{
    "contactId": "3f9a2b1c-4d5e-6f70-8192-a3b4c5d6e7f8",
    "submit": true,
    "totalAmountCents": 125000,
    "customFields": [
      { "fieldId": "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e", "value": "evt-100" }
    ],
    "items": [{ "name": "Stage rental", "quantity": 1, "unitAmountCents": 125000 }]
  }'
```

To set the event on a draft before it goes for approval, send the same `customFields` to `POST /v1/payables/{payableId}/submit`. Your answer replaces any event already on the draft.

An event id the field does not have, or an archived event, fails with `422 validation_error`. Sync your events first.

## Read each bill's event

Every bill carries its answers in `customFields`. Find the answer whose `fieldId` is the Event field:

```json theme={null}
{
  "fieldId": "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e",
  "label": "Event",
  "type": "DROPDOWN",
  "value": {
    "optionId": "2a7c9e1f-4b6d-4c8e-a0f2-3b5d7e9f1a2c",
    "externalId": "evt-100",
    "label": "Spring Gala 2027"
  }
}
```

Map `value.externalId` to your event. Do not match on `label`: it changes when an event is renamed, and two events can share one. An option someone added in the Cleo web app has `externalId: null`. Match it by `optionId` instead.

A bill with no answer has no entry for the field, or an entry whose `value` is `null`. A required field still leaves gaps: bills created before it was required, and drafts, can have no event.

```js theme={null}
const EVENT_FIELD_ID = "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e";

function eventOf(bill) {
  const answer = bill.customFields.find((field) => field.fieldId === EVENT_FIELD_ID);
  if (!answer || answer.value === null || typeof answer.value !== "object") return null;
  return answer.value.externalId ?? answer.value.optionId;
}
```

## List one event's bills

Pass the field id and your event id to `GET /v1/payables`:

```bash theme={null}
curl "https://api.stg.cleo-pay.com/v1/payables?customFieldId=8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e&customFieldValue=evt-100&pageSize=100" \
  --header "Authorization: Bearer $CLEO_API_KEY"
```

`customFieldValue` also takes the option's `id` or `value`. Archived events still match. Walk the pages until you have `totalCount` bills. See [Pagination](https://docs.cleo-pay.com/reference/pagination.md).

To total an event's cost, add up `totalAmountCents`, or `amountPaidCents` for what has been paid. For per-line detail, read each bill with `GET /v1/payables/{payableId}`: its line items carry their own `category` and line-level `customFields`.

## Bills from before the dropdown

If the business used a free-text question for events before, its old bills keep those text answers under the old field's `fieldId`, as plain strings. Cleo does not convert them to options, and the filter does not match them. Map them to your events on your side, for example by reading each bill once and matching the text.

The old field stays on those bills even after it is turned off or deleted, with the label it had then. See [Old and deleted answers](https://docs.cleo-pay.com/concepts/custom-fields.md#old-and-deleted-answers).

## Related

* [Custom fields](https://docs.cleo-pay.com/concepts/custom-fields.md)
* [Sync dropdown options](https://docs.cleo-pay.com/api-reference/payable-custom-fields/sync-options.md)
* [List payables](https://docs.cleo-pay.com/api-reference/payables/list.md)


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