# Get started: from a key to your first price

> Five steps, about ten minutes: create a key, check it, find a base product and price it with shipping. Nothing is saved or charged.

Source: https://docs.b7r.app/get-started

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](https://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:

```bash
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](https://docs.b7r.app/keys-and-access).

Request:

```bash
curl https://api.b7r.app/v1/me \
  -H "Authorization: Bearer $B7R_API_KEY"
```

```javascript
const res = await fetch("https://api.b7r.app/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.B7R_API_KEY}`,
  },
});
const data = await res.json();
```

```python
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:

```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](https://docs.b7r.app/catalog#paging)).

Request:

```bash
curl https://api.b7r.app/v1/catalog/products?limit=20 \
  -H "Authorization: Bearer $B7R_API_KEY"
```

```javascript
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();
```

```python
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:

```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`](https://docs.b7r.app/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.

Request:

```bash
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"
  }'
```

```javascript
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();
```

```python
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:

```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"
  }
}
```

> Done: you checked your key, found a product and priced it. Nothing was saved and nothing was charged.

What next:

- [Keys and access](https://docs.b7r.app/keys-and-access): areas, presets, expiry and revoking.
- [Errors](https://docs.b7r.app/errors): every code, and which ones to retry.
- [Limits and retries](https://docs.b7r.app/limits-and-retries): `429`, `Retry-After` and backoff.
- [For AI agents](https://docs.b7r.app/ai-agents): the rules an agent follows with this API.
