References and external ids

Name records in a request body, and link them to the ids of your own systems.

Version v1.1, updated 5 October 2026

On this page

The three reference shapes
External ids
Two ids for one product
Link or unlink an existing record
Related

A write often names another record: the customer of an order, the product of a line. You can name it by its BIRP id or by the id your own system gives it, its external id.

The three reference shapes

Shape	Example	Finds
By id	`{ "id": "..." }`	The record with that BIRP id.
By external id	`{ "external_id": "1042", "source": "woocommerce" }`	The record linked to that id of that source.
By SKU, products only	`{ "sku": "FP-BREAD-500" }`	The product with that SKU. Add `"kind"` when a goods item and a finished product share it.

A reference finds only records of your company. When it finds nothing, the answer is 422 reference_not_found, naming the field, such as lines[1].product. A SKU shared by two kinds, without kind, answers 409 sku_ambiguous.

External ids

An external id is the id of a record in your own system, stored in BIRP with its source. A source is a short lowercase name of that system, such as woocommerce or erp-main.

Creates and upserts take external_ids: up to 10 pairs of source and external_id.
One source and external id identify one record of the company. Using the pair for a second record answers 409 external_id_conflict.
A record has at most one external id per source. Setting another replaces it.
Every record returns its links in external_ids, and every list finds a record by external_id and source.

Two ids for one product

Some shops give a product two ids, such as a product id and a variant id. Because a record has one external id per source, use one source for each kind of id.

external_idsJSON

{
  "external_ids": [
    {
      "source": "shopify_product",
      "external_id": "example-product-1042"
    },
    {
      "source": "shopify_variant",
      "external_id": "example-variant-1042-1"
    }
  ]
}

Use the variant id for upserts, because a variant carries the SKU and the stock. A shop product with three variants is three BIRP products, each with its own shopify_variant id. Link the shop product id to one of them only, or to none.

Link or unlink an existing record

PUT /v1/{resource}/{id}/external-refs/{source} links a record you already have. DELETE on the same path removes the link only, never the record. See External references.

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

external-references
sync-products
customers
pagination-and-filtering