B7RDevelopers
Get startedGet started
Get started / Get started

Get started: from a key to your first price

View .md

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.

Shell
export B7R_API_KEY="b7r_live_..."  # paste your whole key

Check 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.

Request
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()
200 OK
{
  "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).

Request
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()
200 OK
{
  "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:

Request
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()
200 OK
{
  "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"
  }
}

Titles and headings of every page. llms-full.txt holds the full text.