External references

Link a record to its id in one of your systems, or remove that link.

Version v1.1, updated 5 October 2026

On this page

Fields
Link a record to its id in an external system
Remove the link to an external system
Related

An external reference links a record of BIRP to its id in one of your systems, for one source. These two operations manage the links of records that already exist.

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.

External reference

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
external_id	string	Yes	Yes	Yes
id	string (uuid)	Yes	No	Yes
resource	string	Yes	No	Yes	One of: products, categories, customers, warehouses, orders, invoices.
source	string	Yes	No	Yes

Link a record to its id in an external system

Links a record to its id in one of your systems, or replaces the link of that source.

Scope: the write scope of the resource in the path (products:write, categories:write, customers:write, stock:write, orders:write, invoices:write).
Idempotency: Idempotency-Key accepted and recommended.

{resource} is one of products, categories, customers, warehouses, orders, invoices. The scope is the write scope of that resource; warehouses use stock:write.

PUT/v1/{resource}/{id}/external-refs/{source}

Parameters

resourcerequiredstring, in path: Kind of record: products, categories, customers, warehouses, orders or invoices. The operation needs the write scope of that resource (stock:write for warehouses).One of products, categories, customers, warehouses, orders, invoicesExample products
sourcerequiredstring, in path: External system, in lowercase.Example woocommerce
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: Identifier of the record.Example 00000000-0000-4000-8000-000000000011

Request body

application/json

external_idrequiredstring: Identifier of the record in the external system.

PUT /v1/{resource}/{id}/external-refs/{source}

curl -X PUT "https://api.birp.io/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"1042"}'

const response = await fetch("https://api.birp.io/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "external_id": "1042"
  }),
});
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/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce");
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'
{
  "external_id": "1042"
}
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/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce",
    json={
      "external_id": "1042"
    },
    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": {
    "external_id": "1042",
    "id": "00000000-0000-4000-8000-000000000011",
    "resource": "products",
    "source": "woocommerce"
  }
}

Errors particular to this operation:

404 not_found
409 external_id_conflict
422 validation_failed

Remove the link to an external system

Removes the link of a record for one source. The record itself stays.

Scope: the write scope of the resource in the path (products:write, categories:write, customers:write, stock:write, orders:write, invoices:write).
Idempotency: Idempotency-Key accepted and recommended.

The scope is the write scope of the resource in the path.

DELETE/v1/{resource}/{id}/external-refs/{source}

Parameters

resourcerequiredstring, in path: Kind of record: products, categories, customers, warehouses, orders or invoices. The operation needs the write scope of that resource (stock:write for warehouses).One of products, categories, customers, warehouses, orders, invoicesExample products
sourcerequiredstring, in path: External system, in lowercase.Example woocommerce
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: Identifier of the record. Also answered when the record has no external id for this source.Example 00000000-0000-4000-8000-000000000011

DELETE /v1/{resource}/{id}/external-refs/{source}

curl -X DELETE "https://api.birp.io/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch("https://api.birp.io/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
  },
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);

<?php
$ch = curl_init("https://api.birp.io/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "DELETE",
    "https://api.birp.io/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()

The answer is 204 No Content, with no body.

Errors particular to this operation:

404 not_found
422 validation_failed

references-and-external-ids
sync-products
customers

Fields

Link a record to its id in an external system

Remove the link to an external system

Related