Customers

Customers with their contact details, address and tax details: list, read, create, update and upsert.

Version v1.1, updated 5 October 2026

On this page

Fields
List customers
Get a customer
Create a customer
Update a customer
Create or update a customer by its external id
Create or update up to 100 customers
Related

A customer is a company or a person the company sells to. Orders and invoices name a customer, and an upsert can match the customers BIRP already has.

Fields

Send says the field is in responses. Receive says a write accepts it; a reference is sent as an object, such as category for category_id. Totals, VAT, numbers and statuses are computed by BIRP and never received.

Customer

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
address	Address	Yes	Yes	Yes	Postal address.
contact_name	string or null	No	Yes	Yes	Name of the contact person.
country_code	string or null	No	Yes	Yes	ISO 3166-1 alpha-2 country code, next to the free-text address.country. Null when not recorded.
created_at	string	Yes	No	Yes	Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
customer_type	string or null	No	Yes	Yes	b2b for a company, b2c for a private person. Null when not recorded.
email	string or null	No	Yes	Yes	Contact email. Two customers can share one.
external_ids	array of ExternalId	Yes	Yes	Yes	Identifiers of the customer in external systems.
id	string (uuid)	Yes	No	Yes	Customer identifier.
name	string	Yes	Yes	Yes	Customer name.
phone	string or null	No	Yes	Yes	Contact phone.
registration_number	string or null	No	Yes	Yes	Company registration or tax number, in the format of its country.
updated_at	string	Yes	No	Yes	Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
vat_number	string or null	No	Yes	Yes	VAT number, null when the customer has none.

List customers

Lists the customers of the company.

Scope: customers:read.
Idempotency: a read; send it as often as you need.

GET/v1/customers

Parameters

limitinteger, in query: Page size, 1 to 200. Default 50.Default 50
cursorstring, in query: next_cursor of the previous page. Pages are ordered by id.Example opaque-cursor-example
updated_sincestring (date-time), in query: Only records changed at or after this time: ISO 8601 date and time with an offset or Z.Example 2026-09-01T00:00:00Z
external_idstring, in query: Identifier in an external system. Requires source.Example 1042
sourcestring, in query: External system of external_id, in lowercase. Requires external_id.Example woocommerce
emailstring, in query: Contact email, case-insensitive exact match.Example achats@example.com
tax_idstring, in query: Registration number, exact match, surrounding spaces ignored.Example EXAMPLE-0002

GET /v1/customers

curl "https://api.birp.io/v1/customers" \
  -H "Authorization: Bearer $BIRP_API_KEY"

const response = await fetch("https://api.birp.io/v1/customers", {
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
  },
});
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");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/customers",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": [
    {
      "address": {
        "city": "Paris",
        "country": "France",
        "line1": "12 rue des Exemples",
        "line2": null,
        "postal_code": "00000"
      },
      "contact_name": "Claire Exemple",
      "country_code": "FR",
      "created_at": "2026-09-01T07:30:00.000Z",
      "customer_type": "b2b",
      "email": "achats@example.com",
      "external_ids": [
        {
          "external_id": "cust-77",
          "source": "woocommerce"
        }
      ],
      "id": "00000000-0000-4000-8000-000000000031",
      "name": "Epicerie Exemple SARL",
      "phone": "+33 0 00 00 00 00",
      "registration_number": "EXAMPLE-0002",
      "updated_at": "2026-09-28T14:05:12.417Z",
      "vat_number": "EXAMPLE-VAT-0002"
    },
    {
      "address": {
        "city": "Springfield",
        "country": "United States",
        "line1": "100 Example Street",
        "line2": "Apt 4",
        "postal_code": "00000"
      },
      "contact_name": null,
      "country_code": "US",
      "created_at": "2026-09-28T15:20:01.000Z",
      "customer_type": "b2c",
      "email": "jordan.example@example.org",
      "external_ids": [
        {
          "external_id": "cust-78",
          "source": "woocommerce"
        }
      ],
      "id": "00000000-0000-4000-8000-000000000032",
      "name": "Jordan Example",
      "phone": "+1 000 000 0000",
      "registration_number": null,
      "updated_at": "2026-09-28T15:20:01.000Z",
      "vat_number": null
    },
    {
      "address": {
        "city": "Chisinau",
        "country": "Moldova",
        "line1": "Str. Exemplului 1",
        "line2": null,
        "postal_code": "MD-0000"
      },
      "contact_name": "Ana Exemplu",
      "country_code": "MD",
      "created_at": "2026-09-01T07:30:00.000Z",
      "customer_type": "b2b",
      "email": "comenzi@example.com",
      "external_ids": [],
      "id": "00000000-0000-4000-8000-000000000033",
      "name": "Panificatie Exemplu SRL",
      "phone": "+373 00 000 000",
      "registration_number": "EXAMPLE-0003",
      "updated_at": "2026-09-28T14:05:12.417Z",
      "vat_number": "EXAMPLE-VAT-0003"
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 50,
    "next_cursor": null
  }
}

Errors particular to this operation:

422 validation_failed

Get a customer

Returns one customer of the company.

Scope: customers:read.
Idempotency: a read; send it as often as you need.

GET/v1/customers/{id}

Parameters

idrequiredstring (uuid), in path: Customer identifier.Example 00000000-0000-4000-8000-000000000031

GET /v1/customers/{id}

curl "https://api.birp.io/v1/customers/00000000-0000-4000-8000-000000000031" \
  -H "Authorization: Bearer $BIRP_API_KEY"

const response = await fetch("https://api.birp.io/v1/customers/00000000-0000-4000-8000-000000000031", {
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
  },
});
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/00000000-0000-4000-8000-000000000031");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/customers/00000000-0000-4000-8000-000000000031",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": {
    "address": {
      "city": "Paris",
      "country": "France",
      "line1": "12 rue des Exemples",
      "line2": null,
      "postal_code": "00000"
    },
    "contact_name": "Claire Exemple",
    "country_code": "FR",
    "created_at": "2026-09-01T07:30:00.000Z",
    "customer_type": "b2b",
    "email": "achats@example.com",
    "external_ids": [
      {
        "external_id": "cust-77",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000031",
    "name": "Epicerie Exemple SARL",
    "phone": "+33 0 00 00 00 00",
    "registration_number": "EXAMPLE-0002",
    "updated_at": "2026-09-28T14:05:12.417Z",
    "vat_number": "EXAMPLE-VAT-0002"
  }
}

Errors particular to this operation:

404 not_found

Create a customer

Creates a customer.

Scope: customers:write.
Idempotency: Idempotency-Key required. See Idempotency.

Without country_code, the country of your company applies.

POST/v1/customers

Parameters

Idempotency-Keyrequiredstring, in header: Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE.Example 00000000-0000-4000-8000-0000000000a1

Request body

application/json

namerequiredstring
emailstring | null
phonestring | null
addressCustomerAddressInput: Postal address; country is free text. Members left out are not touched on update.
address.citystring | null
address.line1string | null
address.line2string | null
address.countrystring | null: Free text. Send country_code for the ISO code.
address.postal_codestring | null
vat_numberstring | null
contact_namestring | null
country_codestring | null: ISO 3166-1 alpha-2 country code.
external_idsarray of ExternalIdInput: Identifiers in external systems, at most one per source.
external_ids[].sourcerequiredstring: External system, in lowercase (for example woocommerce, shopify_product).
external_ids[].external_idrequiredstring: Identifier in that system.
customer_typestring | null: b2b for a company, b2c for a private person.One of b2b, b2c
registration_numberstring | null: Registration or tax number, as used in the country.

POST /v1/customers

curl -X POST "https://api.birp.io/v1/customers" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"address":{"city":"Paris","country":"France","line1":"12 rue des Exemples","line2":null,"postal_code":"00000"},"contact_name":"Claire Exemple","country_code":"FR","customer_type":"b2b","email":"achats@example.com","external_ids":[{"external_id":"cust-77","source":"woocommerce"}],"name":"Epicerie Exemple SARL","phone":"+33 0 00 00 00 00","registration_number":"EXAMPLE-0002","vat_number":"EXAMPLE-VAT-0002"}'

const response = await fetch("https://api.birp.io/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "address": {
      "city": "Paris",
      "country": "France",
      "line1": "12 rue des Exemples",
      "line2": null,
      "postal_code": "00000"
    },
    "contact_name": "Claire Exemple",
    "country_code": "FR",
    "customer_type": "b2b",
    "email": "achats@example.com",
    "external_ids": [
      {
        "external_id": "cust-77",
        "source": "woocommerce"
      }
    ],
    "name": "Epicerie Exemple SARL",
    "phone": "+33 0 00 00 00 00",
    "registration_number": "EXAMPLE-0002",
    "vat_number": "EXAMPLE-VAT-0002"
  }),
});
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");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "address": {
    "city": "Paris",
    "country": "France",
    "line1": "12 rue des Exemples",
    "line2": null,
    "postal_code": "00000"
  },
  "contact_name": "Claire Exemple",
  "country_code": "FR",
  "customer_type": "b2b",
  "email": "achats@example.com",
  "external_ids": [
    {
      "external_id": "cust-77",
      "source": "woocommerce"
    }
  ],
  "name": "Epicerie Exemple SARL",
  "phone": "+33 0 00 00 00 00",
  "registration_number": "EXAMPLE-0002",
  "vat_number": "EXAMPLE-VAT-0002"
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "POST",
    "https://api.birp.io/v1/customers",
    json={
      "address": {
        "city": "Paris",
        "country": "France",
        "line1": "12 rue des Exemples",
        "line2": None,
        "postal_code": "00000"
      },
      "contact_name": "Claire Exemple",
      "country_code": "FR",
      "customer_type": "b2b",
      "email": "achats@example.com",
      "external_ids": [
        {
          "external_id": "cust-77",
          "source": "woocommerce"
        }
      ],
      "name": "Epicerie Exemple SARL",
      "phone": "+33 0 00 00 00 00",
      "registration_number": "EXAMPLE-0002",
      "vat_number": "EXAMPLE-VAT-0002"
    },
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

201 CreatedJSON

{
  "data": {
    "address": {
      "city": "Paris",
      "country": "France",
      "line1": "12 rue des Exemples",
      "line2": null,
      "postal_code": "00000"
    },
    "contact_name": "Claire Exemple",
    "country_code": "FR",
    "created_at": "2026-09-01T07:30:00.000Z",
    "customer_type": "b2b",
    "email": "achats@example.com",
    "external_ids": [
      {
        "external_id": "cust-77",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000031",
    "name": "Epicerie Exemple SARL",
    "phone": "+33 0 00 00 00 00",
    "registration_number": "EXAMPLE-0002",
    "updated_at": "2026-09-28T14:05:12.417Z",
    "vat_number": "EXAMPLE-VAT-0002"
  }
}

Errors particular to this operation:

409 external_id_conflict
422 validation_failed

Update a customer

Changes the fields you send and leaves the others as they are.

Scope: customers:write.
Idempotency: Idempotency-Key accepted and recommended.

PATCH/v1/customers/{id}

Parameters

Idempotency-Keystring, in header: Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE.Example 00000000-0000-4000-8000-0000000000a1
idrequiredstring (uuid), in path: Customer identifier.Example 00000000-0000-4000-8000-000000000031

Request body

application/json

namestring
emailstring | null
phonestring | null
addressCustomerAddressInput: Postal address; country is free text. Members left out are not touched on update.
address.citystring | null
address.line1string | null
address.line2string | null
address.countrystring | null: Free text. Send country_code for the ISO code.
address.postal_codestring | null
vat_numberstring | null
contact_namestring | null
country_codestring | null: ISO 3166-1 alpha-2 country code.
customer_typestring | null: b2b for a company, b2c for a private person.One of b2b, b2c
registration_numberstring | null: Registration or tax number, as used in the country.

PATCH /v1/customers/{id}

curl -X PATCH "https://api.birp.io/v1/customers/00000000-0000-4000-8000-000000000031" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"address":{"city":"Paris"},"phone":"+33 0 00 00 00 00"}'

const response = await fetch("https://api.birp.io/v1/customers/00000000-0000-4000-8000-000000000031", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "address": {
      "city": "Paris"
    },
    "phone": "+33 0 00 00 00 00"
  }),
});
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/00000000-0000-4000-8000-000000000031");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "address": {
    "city": "Paris"
  },
  "phone": "+33 0 00 00 00 00"
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "PATCH",
    "https://api.birp.io/v1/customers/00000000-0000-4000-8000-000000000031",
    json={
      "address": {
        "city": "Paris"
      },
      "phone": "+33 0 00 00 00 00"
    },
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": {
    "address": {
      "city": "Paris",
      "country": "France",
      "line1": "12 rue des Exemples",
      "line2": null,
      "postal_code": "00000"
    },
    "contact_name": "Claire Exemple",
    "country_code": "FR",
    "created_at": "2026-09-01T07:30:00.000Z",
    "customer_type": "b2b",
    "email": "achats@example.com",
    "external_ids": [
      {
        "external_id": "cust-77",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000031",
    "name": "Epicerie Exemple SARL",
    "phone": "+33 0 00 00 00 00",
    "registration_number": "EXAMPLE-0002",
    "updated_at": "2026-09-28T14:05:12.417Z",
    "vat_number": "EXAMPLE-VAT-0002"
  }
}

Errors particular to this operation:

404 not_found
422 validation_failed

Create or update a customer by its external id

Creates the customer linked to an external id, or updates it when it exists.

Scope: customers:write.
Idempotency: Idempotency-Key accepted and recommended.

With match_by, an existing customer with the same email or registration number is linked instead of creating a new one. See Match and update customers.

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

Parameters

sourcerequiredstring, in path: External system, in lowercase.Example woocommerce
external_idrequiredstring, in path: Identifier of the customer in that system.Example cust-77
Idempotency-Keystring, in header: Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE.Example 00000000-0000-4000-8000-0000000000a1
match_bystring, in query: When the external id is not linked yet: email, registration_number, or both separated by a comma, tried in that order.Example email

Request body

application/json

namerequiredstring
emailstring | null
phonestring | null
addressCustomerAddressInput: Postal address; country is free text. Members left out are not touched on update.
address.citystring | null
address.line1string | null
address.line2string | null
address.countrystring | null: Free text. Send country_code for the ISO code.
address.postal_codestring | null
vat_numberstring | null
contact_namestring | null
country_codestring | null: ISO 3166-1 alpha-2 country code.
external_idsarray of ExternalIdInput: Identifiers in external systems, at most one per source.
external_ids[].sourcerequiredstring: External system, in lowercase (for example woocommerce, shopify_product).
external_ids[].external_idrequiredstring: Identifier in that system.
customer_typestring | null: b2b for a company, b2c for a private person.One of b2b, b2c
registration_numberstring | null: Registration or tax number, as used in the country.

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()

200 OKJSON

{
  "data": {
    "address": {
      "city": "Paris",
      "country": "France",
      "line1": "12 rue des Exemples",
      "line2": null,
      "postal_code": "00000"
    },
    "contact_name": "Claire Exemple",
    "country_code": "FR",
    "created_at": "2026-09-01T07:30:00.000Z",
    "customer_type": "b2b",
    "email": "achats@example.com",
    "external_ids": [
      {
        "external_id": "cust-77",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000031",
    "name": "Epicerie Exemple SARL",
    "phone": "+33 0 00 00 00 00",
    "registration_number": "EXAMPLE-0002",
    "updated_at": "2026-09-28T14:05:12.417Z",
    "vat_number": "EXAMPLE-VAT-0002"
  }
}

Errors particular to this operation:

409 customer_match_ambiguous
409 external_id_conflict
422 validation_failed

Create or update up to 100 customers

Upserts up to 100 customers in one request and reports the result of each.

Scope: customers:write.
Idempotency: Idempotency-Key required. See Idempotency.

Each item can carry its own match_by. See Batch operations.

POST/v1/customers/batch

Parameters

Idempotency-Keyrequiredstring, in header: Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE.Example 00000000-0000-4000-8000-0000000000a1

Request body

application/json

itemsrequiredarray of CustomerBatchItem
items[].datarequiredCustomerUpsert: A customer by its external id: created when no customer matches, otherwise updated with the fields sent.
items[].matchrequiredCustomerMatch: How to find the customer: id (must exist), or external_id with source. With external_id, match_by also tries email and then registration_number when no customer is linked yet.

POST /v1/customers/batch

curl -X POST "https://api.birp.io/v1/customers/batch" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"data":{"country_code":"FR","customer_type":"b2b","email":"achats@example.com","name":"Epicerie Exemple SARL"},"match":{"external_id":"cust-77","match_by":["email"],"source":"woocommerce"}},{"data":{"country_code":"US","customer_type":"b2c","email":"jordan.example@example.org","name":"Jordan Example"},"match":{"external_id":"cust-78","source":"woocommerce"}}]}'

const response = await fetch("https://api.birp.io/v1/customers/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "items": [
      {
        "data": {
          "country_code": "FR",
          "customer_type": "b2b",
          "email": "achats@example.com",
          "name": "Epicerie Exemple SARL"
        },
        "match": {
          "external_id": "cust-77",
          "match_by": [
            "email"
          ],
          "source": "woocommerce"
        }
      },
      {
        "data": {
          "country_code": "US",
          "customer_type": "b2c",
          "email": "jordan.example@example.org",
          "name": "Jordan Example"
        },
        "match": {
          "external_id": "cust-78",
          "source": "woocommerce"
        }
      }
    ]
  }),
});
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/batch");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "items": [
    {
      "data": {
        "country_code": "FR",
        "customer_type": "b2b",
        "email": "achats@example.com",
        "name": "Epicerie Exemple SARL"
      },
      "match": {
        "external_id": "cust-77",
        "match_by": [
          "email"
        ],
        "source": "woocommerce"
      }
    },
    {
      "data": {
        "country_code": "US",
        "customer_type": "b2c",
        "email": "jordan.example@example.org",
        "name": "Jordan Example"
      },
      "match": {
        "external_id": "cust-78",
        "source": "woocommerce"
      }
    }
  ]
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "POST",
    "https://api.birp.io/v1/customers/batch",
    json={
      "items": [
        {
          "data": {
            "country_code": "FR",
            "customer_type": "b2b",
            "email": "achats@example.com",
            "name": "Epicerie Exemple SARL"
          },
          "match": {
            "external_id": "cust-77",
            "match_by": [
              "email"
            ],
            "source": "woocommerce"
          }
        },
        {
          "data": {
            "country_code": "US",
            "customer_type": "b2c",
            "email": "jordan.example@example.org",
            "name": "Jordan Example"
          },
          "match": {
            "external_id": "cust-78",
            "source": "woocommerce"
          }
        }
      ]
    },
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": {
    "results": [
      {
        "id": "00000000-0000-4000-8000-000000000031",
        "index": 0,
        "status": "updated"
      },
      {
        "id": "00000000-0000-4000-8000-000000000032",
        "index": 1,
        "status": "created"
      }
    ],
    "summary": {
      "created": 1,
      "failed": 0,
      "updated": 1
    }
  }
}

Errors particular to this operation:

422 validation_failed

customers
receive-orders
batches

Fields

List customers

Get a customer

Create a customer

Update a customer

Create or update a customer by its external id

Create or update up to 100 customers

Related