Match and update customers

Link the customers of your system to the customers BIRP already has, and keep them up to date.

Version v1.1, updated 5 October 2026

On this page

Before you start
Steps
Send each customer with an upsert
Ask for a match
Send the tax details
Many customers at once
Check the result
What can go wrong
Related

You will link each customer of your system to one customer in BIRP, matching those BIRP already knows. Every later sync then updates that customer instead of creating another.

Before you start

A key with customers:write and customers:read.
A source name for your system, such as woocommerce.

Steps

Send each customer with an upsert

PUT /v1/customers/external/{source}/{external_id} updates the customer linked to that external id. When none is linked, it creates one, unless you ask it to match first.

Ask for a match

With match_by, a customer whose external id is not linked yet is looked for among the existing customers. The values are email, registration_number, or both separated by a comma, tried in that order.

email matches the email of the body, whatever the letter case.
registration_number matches the registration number of the body, ignoring spaces around it.
One match: the external id is linked to it, and it is updated.
No match: a new customer is created.
Two matches or more: 409 customer_match_ambiguous, and nothing changes.

PUT /v1/customers/external/{source}/{external_id}

curl -X PUT "https://api.birp.io/v1/customers/external/woocommerce/cust-77?match_by=email" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"FR","customer_type":"b2b","email":"achats@example.com","name":"Epicerie Exemple SARL"}'

const response = await fetch("https://api.birp.io/v1/customers/external/woocommerce/cust-77?match_by=email", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "country_code": "FR",
    "customer_type": "b2b",
    "email": "achats@example.com",
    "name": "Epicerie Exemple SARL"
  }),
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/customers/external/woocommerce/cust-77?match_by=email");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "country_code": "FR",
  "customer_type": "b2b",
  "email": "achats@example.com",
  "name": "Epicerie Exemple SARL"
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "PUT",
    "https://api.birp.io/v1/customers/external/woocommerce/cust-77",
    params={"match_by": "email"},
    json={
      "country_code": "FR",
      "customer_type": "b2b",
      "email": "achats@example.com",
      "name": "Epicerie Exemple SARL"
    },
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

Send the tax details

Field	Value
`vat_number`	The VAT number of the customer, as written on invoices.
`registration_number`	The company registration number.
`customer_type`	`b2b` for a company, `b2c` for a private person.
`country_code`	ISO 3166-1 alpha-2, such as `FR`, `US` or `MD`. On a create without it, the country of your company applies.

Many customers at once

POST /v1/customers/batch takes up to 100 customers, each with its own match_by. See Batch operations.

Check the result

GET /v1/customers?source=woocommerce&external_id=cust-77 returns the customer linked to that id.

What can go wrong

Answer	Cause	Fix
409 `customer_match_ambiguous`	More than one customer has that email or registration number.	Link the external id to the right customer with External references, then send the upsert again.
409 `external_id_conflict`	An external id in `external_ids` belongs to another customer.	Remove it there first, or send another one.
422 `validation_failed`	A field is invalid, such as a country code that is not ISO 3166-1.	Fix the field named in `errors`.

customers-resource
receive-orders
references-and-external-ids
batches