Get started: from a key to your first price
Five steps, about ten minutes. You need a verified B7R account and a terminal with curl, Node.js 18 or later, or Python 3 with requests. The Node.js samples use top-level await: save them in a .mjs file.
B7R keys are always live: there is no test mode. Every call in this guide only reads. Nothing is saved and nothing touches your wallet. Amounts, ids and limits in the examples are samples. Read the real values from the API.
Create a key
Sign in to b7r.app and open Settings, then Integrations, then Custom API. Create a key with the Website preset unless you know you need less. Creating a key asks you to accept the API terms, and B7R emails you that a key was made.
The key is shown once. Copy it into your password manager: B7R keeps only a fingerprint of it and cannot show it again. Lost it? Revoke it and create another.
Keep the key on your server
Put the key in an environment variable on the machine that calls the API. Never put it in browser or mobile app code, in a repository or in a URL.
export B7R_API_KEY="b7r_live_..." # paste your whole keyCheck the key
GET /v1/me is the first call with a key in every integration (GET /v1/status needs none and says whether the API is on). It answers your account, the key's name and areas, your live limits and your default carrier. A 401 here means the key is wrong; see Keys and access.
curl https://api.b7r.app/v1/me \
-H "Authorization: Bearer $B7R_API_KEY"const res = await fetch("https://api.b7r.app/v1/me", {
headers: {
Authorization: `Bearer ${process.env.B7R_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://api.b7r.app/v1/me",
headers={
"Authorization": f"Bearer {os.environ['B7R_API_KEY']}",
},
timeout=30,
)
data = res.json(){
"account": {
"id": "a3f1c9e2-5b7d-4e8a-9c21-6d0f4b8e2a17",
"store_name": "Sample Store",
"verified": true,
"active": true
},
"key": {
"name": "Website",
"prefix": "b7r_live_Q7m2Kx9P",
"areas": [
"catalog",
"products:read",
"products:write",
"orders:read",
"orders:write",
"wallet:read"
],
"expires_at": null
},
"limits": {
"calls_per_minute": 120
},
"switches": {
"api_enabled": true,
"connection_enabled": true
},
"default_carrier": {
"id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f",
"name": {
"ar": "شحن سريع",
"en": "Express delivery"
}
}
}Find a base product
The catalog lists the base products on sale: their colours, sizes, printing techniques and print zones, and in options the cost and the minimum selling price of each technique and zone choice. Copy a product id, a technique_id and its zone_ids from one option. Colour and size do not change the price, so a quote does not ask for them. A page can hold fewer products than limit, even none, while next_cursor is set: send it back as cursor until it is null (see Paging).
curl https://api.b7r.app/v1/catalog/products?limit=20 \
-H "Authorization: Bearer $B7R_API_KEY"const res = await fetch("https://api.b7r.app/v1/catalog/products?limit=20", {
headers: {
Authorization: `Bearer ${process.env.B7R_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://api.b7r.app/v1/catalog/products?limit=20",
headers={
"Authorization": f"Bearer {os.environ['B7R_API_KEY']}",
},
timeout=30,
)
data = res.json(){
"data": [
{
"id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
"name": {
"ar": "تيشيرت كلاسيك",
"en": "Classic T-shirt"
},
"colors": [
{
"id": "7a9c1e3f-5b7d-4f9a-8b3c-4d6e8f0a2b4c",
"name": {
"ar": "أسود",
"en": "Black"
},
"hex": "#111111"
},
{
"id": "1c3e5a7b-9d1f-4a3c-9e5b-7f9a1c3e5b7d",
"name": {
"ar": "أبيض",
"en": "White"
},
"hex": "#FFFFFF"
}
],
"sizes": [
{
"id": "3d5f7b9c-1e3a-4c5e-8a7b-9c1d3e5f7a9b",
"name": "M"
},
{
"id": "4e6a8c0d-2f4b-4d6f-9b8c-0d2e4f6a8b0c",
"name": "L"
}
],
"techniques": [
{
"id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"name": {
"ar": "طباعة DTF",
"en": "DTF printing"
}
}
],
"zones": [
{
"id": "5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e",
"name": {
"ar": "الأمام",
"en": "Front"
}
},
{
"id": "6f8b0d2c-4e6a-4c8b-8d2f-3a5b7c9d1e3f",
"name": {
"ar": "الخلف",
"en": "Back"
}
}
],
"options": [
{
"technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"zone_ids": [
"5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
],
"cost": {
"net": "45.00",
"vat": "0.00",
"gross": "45.00",
"currency": "SAR"
},
"minimum_selling_price": {
"amount": "59.00",
"currency": "SAR"
}
},
{
"technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"zone_ids": [
"5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e",
"6f8b0d2c-4e6a-4c8b-8d2f-3a5b7c9d1e3f"
],
"cost": {
"net": "60.00",
"vat": "0.00",
"gross": "60.00",
"currency": "SAR"
},
"minimum_selling_price": {
"amount": "78.00",
"currency": "SAR"
}
}
],
"updated_at": "2026-11-18T09:12:44.512Z"
}
],
"next_cursor": "eyJ1IjoiMjAyNi0xMS0xOCAwOToxMjo0NC41MTIzODErMDAiLCJpIjoiOGMyZTRmNmEifQ"
}Price it with shipping
POST /v1/quote prices a quantity of the product with one carrier: the cost per piece, the lines, the shipping fee and the total, each as net, VAT and gross, plus the minimum selling price. Leave out carrier_id to use your default carrier (default_carrier in GET /v1/me), or pick one from GET /v1/carriers: delivery_method home delivers to the door, pickup to a pickup point. Like every POST it needs an Idempotency-Key; the curl samples make a new one with uuidgen, or Node when uuidgen is missing. A quote takes no address: the carrier fee does not depend on it.
Done: you checked your key, found a product and priced it. Nothing was saved and nothing was charged.
What next:
- Keys and access: areas, presets, expiry and revoking.
- Errors: every code, and which ones to retry.
- Limits and retries:
429,Retry-Afterand backoff. - For AI agents: the rules an agent follows with this API.
curl -X POST https://api.b7r.app/v1/quote \
-H "Authorization: Bearer $B7R_API_KEY" \
-H "Idempotency-Key: $(uuidgen 2>/dev/null || node -e 'console.log(crypto.randomUUID())')" \
-H "Content-Type: application/json" \
-d '{
"product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
"technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"zone_ids": [
"5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
],
"quantity": 2,
"carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f"
}'const res = await fetch("https://api.b7r.app/v1/quote", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.B7R_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
"technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"zone_ids": [
"5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
],
"quantity": 2,
"carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f"
}),
});
const data = await res.json();import os, requests, uuid
res = requests.post(
"https://api.b7r.app/v1/quote",
headers={
"Authorization": f"Bearer {os.environ['B7R_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
"technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"zone_ids": [
"5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
],
"quantity": 2,
"carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f"
},
timeout=30,
)
data = res.json(){
"product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
"technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
"zone_ids": [
"5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
],
"quantity": 2,
"unit_cost": {
"net": "45.00",
"vat": "0.00",
"gross": "45.00",
"currency": "SAR"
},
"lines_total": {
"net": "90.00",
"vat": "0.00",
"gross": "90.00",
"currency": "SAR"
},
"shipping": {
"carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f",
"fee": {
"net": "25.00",
"vat": "0.00",
"gross": "25.00",
"currency": "SAR"
}
},
"total": {
"net": "115.00",
"vat": "0.00",
"gross": "115.00",
"currency": "SAR"
},
"minimum_selling_price": {
"amount": "59.00",
"currency": "SAR"
}
}