Order watches reserved for your business

Bezel reserves inventory for your business at a guaranteed price. The Wholesale API lets your systems see that inventory, place orders paid from your prepaid credit balance, and track every watch through delivery.

Endpoints

Quickstart

Place a sandbox order in four requests. Sandbox has its own listings, orders and balance, and its shipments never move real watches.

1. Check your key

   Bezel issues your sandbox key, which starts with bzl_test_. Confirm it works by listing your accounts.

   RequestCopy

   curl https://<sandbox-api-host>/v1/accounts \
     -H "Authorization: Bearer $BEZEL_API_KEY"

2. See what's reserved for you

   List your active listings. Each one shows the watch, its unit price, how many you can order and how long the offer is guaranteed.

   RequestCopy

   curl "https://<sandbox-api-host>/v1/listings?brand=Rolex" \
     -H "Authorization: Bearer $BEZEL_API_KEY"

3. Save a shipping address

   Addresses are saved once and referenced by ID on orders.

   RequestCopy

   curl https://<sandbox-api-host>/v1/shipping_addresses \
     -H "Authorization: Bearer $BEZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Receiving Dept",
       "company": "Harbor Watch Co.",
       "line1": "500 Madison Ave",
       "city": "New York",
       "region": "NY",
       "postal_code": "10022",
       "country": "US",
       "phone": "+12125550142"
     }'

4. Place an order

   Send a unique Idempotency-Key so a retry never places a second order.

   RequestCopy

   curl https://<sandbox-api-host>/v1/orders \
     -H "Authorization: Bearer $BEZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 5f0c7a52-0c4e-4a8e-9d1b-3a6f2e9b7c11" \
     -d '{
       "customer_reference": "PO-88213",
       "lines": [
         { "listing_id": "lst_9fK2mQ7xR4tB", "quantity": 2, "shipping_address_id": "adr_4Gm7kP2sW9dF" }
       ]
     }'

   Then poll GET /v1/orders/{id} for shipping updates and tracking links.

Authentication

Every request carries a secret API key as a bearer token. Bezel issues keys to you directly; nobody at your business needs a Bezel login.

GET /v1/listings HTTP/1.1
Host: <sandbox-api-host>
Authorization: Bearer bzl_test_8NNUgqIB734YdZBb_ZgHvsXcOG50EMUT5aMfXfunqhSoafa7m904cMj2CO3u0hjA16

• A key acts for exactly one account. An account can have several keys, so you can rotate without downtime.
• Keys look like bzl_<env>_<key id>_<secret>. The 16 characters after the environment are the key's public ID (key_…), which is safe to log.
• A key is shown once when issued and Bezel can't recover it. If you lose one, ask Bezel to revoke it and issue a new one.
• Keys can be issued with an expiry date. A revoked key stops working within a minute.
• Keep keys on your servers. Never put them in a browser, a mobile app or source control.

Environments

A key only works in its own environment. Hostnames will be confirmed before launch.

Permissions

Each key carries the permissions you and Bezel agree on when it's issued. A request outside them gets 403 insufficient_permission. A higher privilege includes the lower ones on the same resource.

Account endpoints work with any valid key.

Conventions

The API speaks JSON over HTTPS with snake_case field names. These rules hold for every endpoint.

IDs

IDs are opaque strings with a type prefix: acc_, lst_, adr_, ord_, itm_, shp_ and key_. Treat them as case-sensitive and allow up to 64 characters.

Money

Amounts are objects with an integer amount in minor units and an ISO 4217 currency. v1 is USD only, so a $14,250.00 watch is:

{ "amount": 1425000, "currency": "USD" }

Timestamps

RFC 3339 strings in UTC, for example 2026-11-11T23:59:59Z.

Pagination

List endpoints return newest first. Pass limit (1 to 100, default 25) and, for the next page, the previous response's next_cursor as cursor. next_cursor is null on the last page.

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0xMS0wNFQyMjoyMDowMFoifQ"
}

Idempotency

POST /v1/orders requires an Idempotency-Key header: any unique string up to 255 characters, such as a UUID. Retrying with the same key and body within 24 hours returns the original response and never places a second order. Reusing a key with a different body returns 409 idempotency_key_reused.

Polling for changes

There are no webhooks in v1. To pick up changes, pass updated_after to GET /v1/listings or GET /v1/orders with the time of your last successful poll.

Rate limits

Limits are per account and will be published before launch. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Over the limit, you get 429 rate_limited with a Retry-After header.

Request IDs

Every response carries a Bezel-Request-Id header. Include it when you contact Bezel about a request.

Versioning

The major version is in the path (/v1). Within v1, Bezel may add endpoints, optional request fields, response fields and enum values without notice, so ignore fields you don't recognize and handle unknown enum values. Removing or renaming anything means a new major version.

Errors

Every error uses the same envelope. Branch on code; message is written for people and may change.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "lines[0].quantity must be at least 1.",
    "param": "lines[0].quantity",
    "request_id": "req_8Hq2LkVw0pXa"
  }
}

The type field groups codes into invalid_request_error, authentication_error, permission_error, balance_error, rate_limit_error and api_error. Retrying POST /v1/orders with the same Idempotency-Key is always safe.

Accounts

An account is your business as a buyer. Listings, shipping addresses, orders and the balance all belong to an account, and your key acts for one account. Most businesses have one account today; every resource carries account_id so a business can hold several later, for example one per storefront.

The account object

{
  "id": "acc_Qm4Tz8Wc1Lr6Hn2V",
  "name": "Harbor Watch Co.",
  "created_at": "2026-11-02T17:45:00Z"
}

List accounts

Returns the accounts your key acts for, newest first, paginated. Today that's always one account, which makes this a quick way to check a new key.

Retrieve an account

Returns one account, or 404 resource_not_found for an account your key doesn't act for.

Listings

A listing is a quantity of one watch reference, in one condition, at one unit price, reserved for your account until valid_until. Before then Bezel never raises the price or takes units back, though it may add units. A new price always arrives as a new listing.

The listing object

{
  "id": "lst_9fK2mQ7xR4tB",
  "account_id": "acc_Qm4Tz8Wc1Lr6Hn2V",
  "status": "active",
  "brand": "Rolex",
  "reference_number": "126610LN",
  "model_name": "Submariner Date",
  "condition": "unworn",
  "box": "yes",
  "papers": "unknown",
  "images": [
    { "url": "https://<image-host>/lst_9fK2mQ7xR4tB/1.jpg", "width": 1600, "height": 1600 }
  ],
  "unit_price": { "amount": 1425000, "currency": "USD" },
  "quantity_available": 4,
  "valid_until": "2026-11-11T23:59:59Z",
  "created_at": "2026-11-04T17:00:00Z",
  "updated_at": "2026-11-04T21:12:40Z"
}

List listings

Returns your listings, newest first, paginated. Without a status filter, only active listings are returned.

Retrieve a listing

Returns one listing in any status. A listing that isn't reserved for you returns 404 resource_not_found, the same as one that doesn't exist.

Shipping addresses

Save each shipping address once and reference it by ID on orders. Bezel validates every new address. If it can't verify one, you can still save it as unverified, and orders to it are still filled. Addresses can't be edited; to change one, save a new address and delete the old one.

The shipping address object

Save a shipping address

Send the address fields above, without id, account_id, verification_status or created_at, plus an optional allow_unverified boolean that defaults to false.

1. If Bezel recognizes the address, it's saved as verified and you get 201.
2. If not, and allow_unverified is false, you get 400 address_unverified and nothing is saved. Show the address to the person entering it and ask whether to save it anyway.
3. If they confirm, send it again with allow_unverified: true. It's saved as unverified and you get 201.

{
  "name": "Receiving Dept",
  "company": "Harbor Watch Co.",
  "line1": "500 Madison Ave",
  "city": "New York",
  "region": "NY",
  "postal_code": "10022",
  "country": "US",
  "phone": "+12125550142",
  "allow_unverified": false
}

List shipping addresses

Returns your saved addresses, newest first, paginated. Filter with verification_status.

Retrieve a shipping address

Delete a shipping address

Returns 204. The address no longer appears when you list or retrieve addresses and can't be used on new orders. Orders that already use it keep it and still ship to it.

Orders

An order buys watches from one or more of your listings and debits your balance in the same step. Each watch becomes its own order item, so items move through shipping independently and can go to different addresses.

The order object

The order item object

The shipment object

Place an order

The body lists up to 50 lines. Each line names a listing, a quantity and the shipping_address_id those watches ship to. Use two lines for the same listing to split it across addresses.

{
  "customer_reference": "PO-88213",
  "lines": [
    { "listing_id": "lst_9fK2mQ7xR4tB", "quantity": 2, "shipping_address_id": "adr_4Gm7kP2sW9dF" },
    { "listing_id": "lst_3Wd8pZ1nE6yH", "quantity": 1, "shipping_address_id": "adr_8Rt1yN5vB3hJ" }
  ]
}

Bezel places the order in one atomic step:

1. It validates the request. A malformed body, an unknown listing or an unknown address rejects the whole request with 400, and nothing is placed. Unverified addresses are accepted.
2. It fills each line in order with as many watches as the listing has left, up to the quantity asked. An expired or sold-out listing fills nothing.
3. If nothing could be filled, it returns 409 no_units_available and places nothing.
4. If the filled total is more than your balance, it returns 402 insufficient_balance and places nothing. Your balance never causes a partial fill.
5. Otherwise it debits the filled total, reduces each listing's quantity and returns 201 with the order.

Because listings are reserved for you, a line only falls short when your own concurrent orders took the units first or the listing expired. Any shortfall is recorded in unfilled with a reason of insufficient_quantity or listing_expired. Always check unfilled before treating an order as complete.

{
  "id": "ord_7Tn4cX2qL9vA",
  "account_id": "acc_Qm4Tz8Wc1Lr6Hn2V",
  "status": "open",
  "customer_reference": "PO-88213",
  "items": [
    {
      "id": "itm_1aB2cD3eF4gH",
      "line_index": 0,
      "listing_id": "lst_9fK2mQ7xR4tB",
      "brand": "Rolex",
      "reference_number": "126610LN",
      "model_name": "Submariner Date",
      "condition": "unworn",
      "box": "yes",
      "papers": "yes",
      "unit_price": { "amount": 1425000, "currency": "USD" },
      "status": "awaiting_shipment",
      "shipping_address": { "id": "adr_4Gm7kP2sW9dF", "verification_status": "verified", "…": "…" },
      "shipment_id": null,
      "cancellation_reason": null,
      "shipped_at": null,
      "delivered_at": null,
      "cancelled_at": null
    }
  ],
  "unfilled": [
    { "line_index": 0, "listing_id": "lst_9fK2mQ7xR4tB", "quantity": 1, "reason": "insufficient_quantity" },
    { "line_index": 1, "listing_id": "lst_3Wd8pZ1nE6yH", "quantity": 1, "reason": "listing_expired" }
  ],
  "shipments": [],
  "amount_charged": { "amount": 1425000, "currency": "USD" },
  "amount_refunded": { "amount": 0, "currency": "USD" },
  "created_at": "2026-11-04T22:31:05Z",
  "updated_at": "2026-11-04T22:31:05Z",
  "closed_at": null
}

There's no cancel endpoint in v1. To cancel an order, contact Bezel.

Order item lifecycle

Each watch moves through shipping on its own. The order stays open until every item is delivered or cancelled.

When an item is cancelled, its unit_price is refunded to your balance and added to the order's amount_refunded. A watch that arrives damaged stays delivered; contact Bezel to resolve it.

List orders

Returns your orders, newest first, paginated.

Retrieve an order

Returns one order with its items, unfilled lines and shipments.

Balance

Your balance is prepaid credit in USD. Bezel adds credits for you; there's no top-up endpoint. Orders debit it in full when placed, cancelled items are refunded to it, and it never goes negative.

{
  "account_id": "acc_Qm4Tz8Wc1Lr6Hn2V",
  "available": { "amount": 8575000, "currency": "USD" },
  "updated_at": "2026-11-04T22:31:05Z"
}

Share feedback

The Wholesale API is still taking shape, and we're building it with the partners who will use it. If something here doesn't fit how your business buys, is missing, or is harder than it should be, we want to hear about it.

Send your thoughts to your Bezel contact at any point. No feedback is too small, and anything in this preview can change before launch.