A Customer is one of your B2B accounts — the party that sends you the LVs Mercura processes. Each customer is keyed by the customer_id you assign in your source system. Address is sent as an addresses[] array on write, but Mercura persists and returns exactly one (the is_default entry, else the first); extra entries are dropped. Contact persons live on the separate /contacts resource (each contact references its parent by parent_type + parent_id). Mercura uses this data both to resolve the customer on incoming LVs and to populate the customer block of every offer you read back.
You can:
POST /customers— bulk-upsert up to 100,000 customers in a single call. Async — returns aJobAck; pollGET /jobs/{job_id}for status. Existing customers are updated in place bycustomer_id; new ones are inserted.GET /customers— cursor-paginated list of your customers. Usemodified_sincefor delta-sync.GET /customers/{customer_id}— fetch a single customer by the partner-supplied id.
Read responses (GET /customers, GET /customers/{customer_id}, and the customer block of every offer) return custom_fields keyed by the field's display label — the same label you see in the Mercura admin UI — rather than the internal column id. Columns with no active definition are omitted. If two custom columns share a label, the one defined first (by display order, then creation time) wins and the other's value is dropped from the response; deduplicate colliding columns in the admin UI. The same label-keying applies to suppliers.
The write path is deliberately asymmetric: on POST /customers send custom_fields keyed by the internal column id (not the label). Only reads are label-keyed.