Orders

Customer orders with their lines: list, read, create, change a draft, confirm and cancel.

Version v1.1, updated 5 October 2026

On this page

Fields
List orders
Get an order
Create an order
Update a draft order
Confirm a draft order
Cancel an order
Related

An order is what a customer asked for, with its lines, prices and addresses. It starts as a draft, and its status changes only through the confirm and cancel actions.

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.

Order

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
billing_address	OrderAddress or null	No	Yes	Yes	Billing address sent with the order; null when none was sent.
confirmed_at	string or null	No	No	Yes	Confirmation time, or null. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
contact	Contact	Yes	No	Yes	Contact person of the customer for this order.
created_at	string	Yes	No	Yes	Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
currency	string or null	No	Yes	Yes	ISO 4217 code of the order; null when the order has none.
customer_id	string (uuid) or null	No	Yes	Yes	Customer of the order.
delivered_at	string or null	No	No	Yes	Delivery date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
document_kind	string or null	No	No	Yes	order, for an order or for a quote that became an order when it was confirmed. Quotes that are not confirmed are not listed.
expected_at	string or null	No	Yes	Yes	Expected delivery date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
external_ids	array of ExternalId	Yes	No	Yes	Identifiers of the order in external systems.
id	string (uuid)	Yes	No	Yes	Order identifier.
lines	array of OrderLine	Yes	Yes	Yes	Ordered products.
notes	string or null	No	Yes	Yes	Notes sent with the order.
number	string	Yes	No	Yes	Order number, unique per company.
ordered_at	string or null	No	Yes	Yes	Order date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
shipping_address	OrderAddress or null	No	Yes	Yes	Shipping address sent with the order; null when none was sent.
source	string or null	No	Yes	Yes	System the order came from, for example woocommerce. Null for orders made in BIRP.
status	string	Yes	No	Yes	Status of the order. Treat a value outside this list as unknown. One of: draft, confirmed, in_production, ready, prepared, in_delivery, delivered, cancelled, returned.
total	string or null	No	No	Yes	Order total. Decimal string with two decimals.
updated_at	string	Yes	No	Yes	Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.

Order line

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
description	string or null	No	Yes	Yes	Line description sent with the order, if any.
name	string or null	No	No	Yes	Product name at the time of the order.
product_id	string (uuid) or null	No	No	Yes	Product of the line; null when the line names no product.
product_kind	string or null	No	No	Yes	Kind of the product; null without product_id. intermediate_product: a product the company makes for use in its own production. One of: finished_product, intermediate_product.
quantity	string or null	No	Yes	Yes	Ordered quantity, decimal string, or null; when it is null, quantity_raw gives the quantity as text.
quantity_raw	string	No	No	Yes	The quantity as text, present only when quantity is null.
sku	string or null	No	No	Yes	Product reference at the time of the order.
unit	string or null	No	Yes	Yes	Unit of the quantity.
unit_price	string or null	No	Yes	Yes	Unit price, decimal string with four decimals; null when the line has no price.

List orders

Lists the customer orders of the company, and the quotes that became orders.

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

GET/v1/orders

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
statusstring, in query: Order status.One of draft, confirmed, in_production, ready, prepared, in_delivery, delivered, cancelled, returnedExample confirmed
customer_idstring (uuid), in query: Orders of one customer.Example 00000000-0000-4000-8000-000000000031

GET /v1/orders

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

const response = await fetch("https://api.birp.io/v1/orders", {
  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/orders");
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/orders",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": [
    {
      "billing_address": null,
      "confirmed_at": "2026-09-27T08:05:00.000Z",
      "contact": {
        "email": "achats@example.com",
        "name": "Claire Exemple",
        "phone": "+33 0 00 00 00 00"
      },
      "created_at": "2026-09-27T08:00:03.000Z",
      "currency": "EUR",
      "customer_id": "00000000-0000-4000-8000-000000000031",
      "delivered_at": null,
      "document_kind": "order",
      "expected_at": "2026-09-29T06:00:00.000Z",
      "external_ids": [
        {
          "external_id": "order-5512",
          "source": "woocommerce"
        }
      ],
      "id": "00000000-0000-4000-8000-000000000051",
      "lines": [
        {
          "description": null,
          "name": "White bread 500 g",
          "product_id": "00000000-0000-4000-8000-000000000012",
          "product_kind": "finished_product",
          "quantity": "20",
          "sku": "FP-BREAD-500",
          "unit": "pcs",
          "unit_price": "3.2000"
        }
      ],
      "notes": "Deliver before 7:00",
      "number": "EXAMPLE-ORD-0412",
      "ordered_at": "2026-09-27T08:00:00.000Z",
      "shipping_address": {
        "city": "Paris",
        "company": "Epicerie Exemple SARL",
        "country_code": "FR",
        "email": null,
        "line1": "12 rue des Exemples",
        "line2": null,
        "name": "Claire Exemple",
        "phone": "+33 0 00 00 00 00",
        "postal_code": "00000",
        "region": null
      },
      "source": "woocommerce",
      "status": "confirmed",
      "total": "64.00",
      "updated_at": "2026-09-28T14:05:12.417Z"
    },
    {
      "billing_address": null,
      "confirmed_at": null,
      "contact": {
        "email": "jordan.example@example.org",
        "name": "Jordan Example",
        "phone": "+1 000 000 0000"
      },
      "created_at": "2026-09-28T15:20:02.000Z",
      "currency": "USD",
      "customer_id": "00000000-0000-4000-8000-000000000032",
      "delivered_at": null,
      "document_kind": "order",
      "expected_at": null,
      "external_ids": [
        {
          "external_id": "order-5513",
          "source": "woocommerce"
        }
      ],
      "id": "00000000-0000-4000-8000-000000000052",
      "lines": [
        {
          "description": null,
          "name": "White bread 500 g",
          "product_id": "00000000-0000-4000-8000-000000000012",
          "product_kind": "finished_product",
          "quantity": "2",
          "sku": "FP-BREAD-500",
          "unit": "pcs",
          "unit_price": "3.5000"
        }
      ],
      "notes": null,
      "number": "EXAMPLE-ORD-0413",
      "ordered_at": "2026-09-28T15:20:00.000Z",
      "shipping_address": {
        "city": "Springfield",
        "company": null,
        "country_code": "US",
        "email": "jordan.example@example.org",
        "line1": "100 Example Street",
        "line2": "Apt 4",
        "name": "Jordan Example",
        "phone": "+1 000 000 0000",
        "postal_code": "00000",
        "region": "IL"
      },
      "source": "woocommerce",
      "status": "draft",
      "total": "7.00",
      "updated_at": "2026-09-28T15:20:02.000Z"
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 50,
    "next_cursor": null
  }
}

Errors particular to this operation:

422 validation_failed

Get an order

Returns one order of the company, with its lines.

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

GET/v1/orders/{id}

Parameters

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

GET /v1/orders/{id}

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

const response = await fetch("https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051", {
  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/orders/00000000-0000-4000-8000-000000000051");
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/orders/00000000-0000-4000-8000-000000000051",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": {
    "billing_address": null,
    "confirmed_at": "2026-09-27T08:05:00.000Z",
    "contact": {
      "email": "achats@example.com",
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00"
    },
    "created_at": "2026-09-27T08:00:03.000Z",
    "currency": "EUR",
    "customer_id": "00000000-0000-4000-8000-000000000031",
    "delivered_at": null,
    "document_kind": "order",
    "expected_at": "2026-09-29T06:00:00.000Z",
    "external_ids": [
      {
        "external_id": "order-5512",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000051",
    "lines": [
      {
        "description": null,
        "name": "White bread 500 g",
        "product_id": "00000000-0000-4000-8000-000000000012",
        "product_kind": "finished_product",
        "quantity": "20",
        "sku": "FP-BREAD-500",
        "unit": "pcs",
        "unit_price": "3.2000"
      }
    ],
    "notes": "Deliver before 7:00",
    "number": "EXAMPLE-ORD-0412",
    "ordered_at": "2026-09-27T08:00:00.000Z",
    "shipping_address": {
      "city": "Paris",
      "company": "Epicerie Exemple SARL",
      "country_code": "FR",
      "email": null,
      "line1": "12 rue des Exemples",
      "line2": null,
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00",
      "postal_code": "00000",
      "region": null
    },
    "source": "woocommerce",
    "status": "confirmed",
    "total": "64.00",
    "updated_at": "2026-09-28T14:05:12.417Z"
  }
}

Errors particular to this operation:

404 not_found

Create an order

Creates an order as a draft, with its customer, lines and addresses.

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

Lines take finished products. With source and external_id, a second import of the same order is refused. See Receive orders from a shop.

POST/v1/orders

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

linesrequiredarray of OrderLineCreate
lines[].unitstring: Unit of the quantity. Left out: the default unit of the product.
lines[].productrequiredProductReference: A finished product of the company (orders of resale goods are not supported in this version).
lines[].quantityrequiredstring: Decimal string, at most three decimals, above zero.
lines[].unit_pricerequiredstring: Unit price, decimal string, at most four decimals.
lines[].descriptionstring | null
notesstring | null
sourcestring: System the order comes from, in lowercase. Sent with external_id.
currencystring: ISO 4217 code. Left out on create: the company base currency.
customerReference: An existing customer of the company.
customer.idstring (uuid): BIRP id of the record.
customer.sourcestring: External system of external_id, in lowercase.
customer.external_idstring: Identifier of the record in an external system. Requires source.
ordered_atstring: When the order was placed, ISO 8601 date and time with an offset or Z. Left out: now.
expected_atstring: Expected delivery, ISO 8601 date and time with an offset or Z. Left out on create: ordered_at.
external_idstring: Order number in that system. Linked as the order external id: the same order cannot be imported twice.
billing_addressOrderAddressInput | null: Billing or shipping address of an order. Every member is optional.
billing_address.citystring | null
billing_address.namestring | null
billing_address.emailstring | null
billing_address.line1string | null
billing_address.line2string | null
billing_address.phonestring | null
billing_address.regionstring | null
billing_address.companystring | null
billing_address.postal_codestring | null
billing_address.country_codestring | null: ISO 3166-1 alpha-2.
customer_upsertCustomerUpsertInline: A customer created or updated with the order, by its external id. Needs customers:write as well.
customer_upsert.datarequiredCustomerUpsert: A customer by its external id: created when no customer matches, otherwise updated with the fields sent.
customer_upsert.sourcerequiredstring
customer_upsert.match_byarray of string
customer_upsert.external_idrequiredstring
shipping_addressOrderAddressInput | null: Billing or shipping address of an order. Every member is optional.
shipping_address.citystring | null
shipping_address.namestring | null
shipping_address.emailstring | null
shipping_address.line1string | null
shipping_address.line2string | null
shipping_address.phonestring | null
shipping_address.regionstring | null
shipping_address.companystring | null
shipping_address.postal_codestring | null
shipping_address.country_codestring | null: ISO 3166-1 alpha-2.

POST /v1/orders

curl -X POST "https://api.birp.io/v1/orders" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"currency":"EUR","customer":{"external_id":"cust-77","source":"woocommerce"},"expected_at":"2026-09-29T06:00:00Z","external_id":"order-5512","lines":[{"product":{"sku":"FP-BREAD-500"},"quantity":"20","unit_price":"3.20"}],"notes":"Deliver before 7:00","ordered_at":"2026-09-27T08:00:00Z","shipping_address":{"city":"Paris","company":"Epicerie Exemple SARL","country_code":"FR","email":null,"line1":"12 rue des Exemples","line2":null,"name":"Claire Exemple","phone":"+33 0 00 00 00 00","postal_code":"00000","region":null},"source":"woocommerce"}'

const response = await fetch("https://api.birp.io/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "currency": "EUR",
    "customer": {
      "external_id": "cust-77",
      "source": "woocommerce"
    },
    "expected_at": "2026-09-29T06:00:00Z",
    "external_id": "order-5512",
    "lines": [
      {
        "product": {
          "sku": "FP-BREAD-500"
        },
        "quantity": "20",
        "unit_price": "3.20"
      }
    ],
    "notes": "Deliver before 7:00",
    "ordered_at": "2026-09-27T08:00:00Z",
    "shipping_address": {
      "city": "Paris",
      "company": "Epicerie Exemple SARL",
      "country_code": "FR",
      "email": null,
      "line1": "12 rue des Exemples",
      "line2": null,
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00",
      "postal_code": "00000",
      "region": null
    },
    "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/orders");
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'
{
  "currency": "EUR",
  "customer": {
    "external_id": "cust-77",
    "source": "woocommerce"
  },
  "expected_at": "2026-09-29T06:00:00Z",
  "external_id": "order-5512",
  "lines": [
    {
      "product": {
        "sku": "FP-BREAD-500"
      },
      "quantity": "20",
      "unit_price": "3.20"
    }
  ],
  "notes": "Deliver before 7:00",
  "ordered_at": "2026-09-27T08:00:00Z",
  "shipping_address": {
    "city": "Paris",
    "company": "Epicerie Exemple SARL",
    "country_code": "FR",
    "email": null,
    "line1": "12 rue des Exemples",
    "line2": null,
    "name": "Claire Exemple",
    "phone": "+33 0 00 00 00 00",
    "postal_code": "00000",
    "region": null
  },
  "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/orders",
    json={
      "currency": "EUR",
      "customer": {
        "external_id": "cust-77",
        "source": "woocommerce"
      },
      "expected_at": "2026-09-29T06:00:00Z",
      "external_id": "order-5512",
      "lines": [
        {
          "product": {
            "sku": "FP-BREAD-500"
          },
          "quantity": "20",
          "unit_price": "3.20"
        }
      ],
      "notes": "Deliver before 7:00",
      "ordered_at": "2026-09-27T08:00:00Z",
      "shipping_address": {
        "city": "Paris",
        "company": "Epicerie Exemple SARL",
        "country_code": "FR",
        "email": None,
        "line1": "12 rue des Exemples",
        "line2": None,
        "name": "Claire Exemple",
        "phone": "+33 0 00 00 00 00",
        "postal_code": "00000",
        "region": None
      },
      "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()

201 CreatedJSON

{
  "data": {
    "billing_address": null,
    "confirmed_at": null,
    "contact": {
      "email": "achats@example.com",
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00"
    },
    "created_at": "2026-09-27T08:00:03.000Z",
    "currency": "EUR",
    "customer_id": "00000000-0000-4000-8000-000000000031",
    "delivered_at": null,
    "document_kind": "order",
    "expected_at": "2026-09-29T06:00:00.000Z",
    "external_ids": [
      {
        "external_id": "order-5512",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000051",
    "lines": [
      {
        "description": null,
        "name": "White bread 500 g",
        "product_id": "00000000-0000-4000-8000-000000000012",
        "product_kind": "finished_product",
        "quantity": "20",
        "sku": "FP-BREAD-500",
        "unit": "pcs",
        "unit_price": "3.2000"
      }
    ],
    "notes": "Deliver before 7:00",
    "number": "EXAMPLE-ORD-0412",
    "ordered_at": "2026-09-27T08:00:00.000Z",
    "shipping_address": {
      "city": "Paris",
      "company": "Epicerie Exemple SARL",
      "country_code": "FR",
      "email": null,
      "line1": "12 rue des Exemples",
      "line2": null,
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00",
      "postal_code": "00000",
      "region": null
    },
    "source": "woocommerce",
    "status": "draft",
    "total": "64.00",
    "updated_at": "2026-09-28T14:05:12.417Z"
  }
}

Errors particular to this operation:

409 external_id_conflict
409 sku_ambiguous
422 reference_not_found
422 validation_failed

Update a draft order

Changes a draft order: lines, currency, addresses, expected date and notes.

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

The customer and the order date stay as created. A confirmed order no longer changes through the API.

PATCH/v1/orders/{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: Order identifier.Example 00000000-0000-4000-8000-000000000051

Request body

application/json

linesarray of OrderLineCreate
lines[].unitstring: Unit of the quantity. Left out: the default unit of the product.
lines[].productrequiredProductReference: A finished product of the company (orders of resale goods are not supported in this version).
lines[].quantityrequiredstring: Decimal string, at most three decimals, above zero.
lines[].unit_pricerequiredstring: Unit price, decimal string, at most four decimals.
lines[].descriptionstring | null
notesstring | null
currencystring: ISO 4217 code. Left out on create: the company base currency.
expected_atstring: Expected delivery, ISO 8601 date and time with an offset or Z. Left out on create: ordered_at.
billing_addressOrderAddressInput | null: Billing or shipping address of an order. Every member is optional.
billing_address.citystring | null
billing_address.namestring | null
billing_address.emailstring | null
billing_address.line1string | null
billing_address.line2string | null
billing_address.phonestring | null
billing_address.regionstring | null
billing_address.companystring | null
billing_address.postal_codestring | null
billing_address.country_codestring | null: ISO 3166-1 alpha-2.
shipping_addressOrderAddressInput | null: Billing or shipping address of an order. Every member is optional.
shipping_address.citystring | null
shipping_address.namestring | null
shipping_address.emailstring | null
shipping_address.line1string | null
shipping_address.line2string | null
shipping_address.phonestring | null
shipping_address.regionstring | null
shipping_address.companystring | null
shipping_address.postal_codestring | null
shipping_address.country_codestring | null: ISO 3166-1 alpha-2.

PATCH /v1/orders/{id}

curl -X PATCH "https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"expected_at":"2026-09-29T06:00:00Z","notes":"Deliver before 7:00"}'

const response = await fetch("https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "expected_at": "2026-09-29T06:00:00Z",
    "notes": "Deliver before 7: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/orders/00000000-0000-4000-8000-000000000051");
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'
{
  "expected_at": "2026-09-29T06:00:00Z",
  "notes": "Deliver before 7: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/orders/00000000-0000-4000-8000-000000000051",
    json={
      "expected_at": "2026-09-29T06:00:00Z",
      "notes": "Deliver before 7: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": {
    "billing_address": null,
    "confirmed_at": null,
    "contact": {
      "email": "achats@example.com",
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00"
    },
    "created_at": "2026-09-27T08:00:03.000Z",
    "currency": "EUR",
    "customer_id": "00000000-0000-4000-8000-000000000031",
    "delivered_at": null,
    "document_kind": "order",
    "expected_at": "2026-09-29T06:00:00.000Z",
    "external_ids": [
      {
        "external_id": "order-5512",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000051",
    "lines": [
      {
        "description": null,
        "name": "White bread 500 g",
        "product_id": "00000000-0000-4000-8000-000000000012",
        "product_kind": "finished_product",
        "quantity": "20",
        "sku": "FP-BREAD-500",
        "unit": "pcs",
        "unit_price": "3.2000"
      }
    ],
    "notes": "Deliver before 7:00",
    "number": "EXAMPLE-ORD-0412",
    "ordered_at": "2026-09-27T08:00:00.000Z",
    "shipping_address": {
      "city": "Paris",
      "company": "Epicerie Exemple SARL",
      "country_code": "FR",
      "email": null,
      "line1": "12 rue des Exemples",
      "line2": null,
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00",
      "postal_code": "00000",
      "region": null
    },
    "source": "woocommerce",
    "status": "draft",
    "total": "64.00",
    "updated_at": "2026-09-28T14:05:12.417Z"
  }
}

Errors particular to this operation:

404 not_found
409 invalid_status_transition
422 validation_failed

Confirm a draft order

Confirms a draft order.

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

The order keeps the time of confirmation in confirmed_at.

POST/v1/orders/{id}/confirm

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
idrequiredstring (uuid), in path: Order identifier.Example 00000000-0000-4000-8000-000000000051

Request body

application/json, OrderConfirm

POST /v1/orders/{id}/confirm

curl -X POST "https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051/confirm" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch("https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051/confirm", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
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/orders/00000000-0000-4000-8000-000000000051/confirm");
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'
{}
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/orders/00000000-0000-4000-8000-000000000051/confirm",
    json={},
    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": {
    "billing_address": null,
    "confirmed_at": "2026-09-27T08:05:00.000Z",
    "contact": {
      "email": "achats@example.com",
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00"
    },
    "created_at": "2026-09-27T08:00:03.000Z",
    "currency": "EUR",
    "customer_id": "00000000-0000-4000-8000-000000000031",
    "delivered_at": null,
    "document_kind": "order",
    "expected_at": "2026-09-29T06:00:00.000Z",
    "external_ids": [
      {
        "external_id": "order-5512",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000051",
    "lines": [
      {
        "description": null,
        "name": "White bread 500 g",
        "product_id": "00000000-0000-4000-8000-000000000012",
        "product_kind": "finished_product",
        "quantity": "20",
        "sku": "FP-BREAD-500",
        "unit": "pcs",
        "unit_price": "3.2000"
      }
    ],
    "notes": "Deliver before 7:00",
    "number": "EXAMPLE-ORD-0412",
    "ordered_at": "2026-09-27T08:00:00.000Z",
    "shipping_address": {
      "city": "Paris",
      "company": "Epicerie Exemple SARL",
      "country_code": "FR",
      "email": null,
      "line1": "12 rue des Exemples",
      "line2": null,
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00",
      "postal_code": "00000",
      "region": null
    },
    "source": "woocommerce",
    "status": "confirmed",
    "total": "64.00",
    "updated_at": "2026-09-28T14:05:12.417Z"
  }
}

Errors particular to this operation:

404 not_found
409 invalid_status_transition
422 validation_failed

Cancel an order

Cancels a draft or confirmed order, with a reason.

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

An order already in production is cancelled in BIRP, not through the API.

POST/v1/orders/{id}/cancel

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
idrequiredstring (uuid), in path: Order identifier.Example 00000000-0000-4000-8000-000000000051

Request body

application/json

reasonrequiredstring

POST /v1/orders/{id}/cancel

curl -X POST "https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051/cancel" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cancelled by the customer in the shop"}'

const response = await fetch("https://api.birp.io/v1/orders/00000000-0000-4000-8000-000000000051/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "Cancelled by the customer in the shop"
  }),
});
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/orders/00000000-0000-4000-8000-000000000051/cancel");
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'
{
  "reason": "Cancelled by the customer in the shop"
}
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/orders/00000000-0000-4000-8000-000000000051/cancel",
    json={
      "reason": "Cancelled by the customer in the shop"
    },
    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": {
    "billing_address": null,
    "confirmed_at": "2026-09-27T08:05:00.000Z",
    "contact": {
      "email": "achats@example.com",
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00"
    },
    "created_at": "2026-09-27T08:00:03.000Z",
    "currency": "EUR",
    "customer_id": "00000000-0000-4000-8000-000000000031",
    "delivered_at": null,
    "document_kind": "order",
    "expected_at": "2026-09-29T06:00:00.000Z",
    "external_ids": [
      {
        "external_id": "order-5512",
        "source": "woocommerce"
      }
    ],
    "id": "00000000-0000-4000-8000-000000000051",
    "lines": [
      {
        "description": null,
        "name": "White bread 500 g",
        "product_id": "00000000-0000-4000-8000-000000000012",
        "product_kind": "finished_product",
        "quantity": "20",
        "sku": "FP-BREAD-500",
        "unit": "pcs",
        "unit_price": "3.2000"
      }
    ],
    "notes": "Deliver before 7:00",
    "number": "EXAMPLE-ORD-0412",
    "ordered_at": "2026-09-27T08:00:00.000Z",
    "shipping_address": {
      "city": "Paris",
      "company": "Epicerie Exemple SARL",
      "country_code": "FR",
      "email": null,
      "line1": "12 rue des Exemples",
      "line2": null,
      "name": "Claire Exemple",
      "phone": "+33 0 00 00 00 00",
      "postal_code": "00000",
      "region": null
    },
    "source": "woocommerce",
    "status": "cancelled",
    "total": "64.00",
    "updated_at": "2026-09-28T14:05:12.417Z"
  }
}

Errors particular to this operation:

404 not_found
409 invalid_status_transition
422 validation_failed

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

Fields

List orders

Get an order

Create an order

Update a draft order

Confirm a draft order

Cancel an order

Related