API and webhooks

The partner API connects BoutiqVerse with your warehouse, ERP or your own shop. It is deliberately small: catalogue, stock, orders and parcel handover – as much as a sync needs.

API keys

Create a key in the panel: Settings → API keys. We show it only once, when it is created – save it right away, because we store only its hash. Every key has its own scopes, and a revoked key stops working.

Address and authentication

Send the key in the Authorization (Bearer) or X-API-Key header. The limit is 120 requests per minute per key – above it you get a 429 response.

https://www.boutiqverse.com/api/partner
Authorization: Bearer $BOUTIQVERSE_API_KEY
X-API-Key: $BOUTIQVERSE_API_KEY

Sandbox: test keys

Create a test key in the same place (Settings → API keys) by ticking “Test key”. It starts with btk_test_ and works on the demo shop's data, not on your shop. Reading the catalogue and orders is real, while stock changes and parcel handover get the same answer as for real – with a sandbox: true field – but save nothing. The response also carries the X-BoutiqVerse-Sandbox header.

Check a webhook with the “Send a test event” button in Settings → Webhooks: a webhook.test event arrives with the same signature as real ones.

Scopes

products:read – read the catalogue
stock:write – set stock
orders:read – read orders
orders:write – hand over a tracking number

GET /products

Required scope: products:read

The boutique's catalogue with stock per size, newest products first. Parameters: limit (1 to 500, 100 by default) and offset.

Example

curl "https://www.boutiqverse.com/api/partner/products?limit=100&offset=0" \
  -H "Authorization: Bearer $BOUTIQVERSE_API_KEY"

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "5f0c8a52-…",
        "name": "Sukienka Lena",
        "slug": "sukienka-lena-5f0c8a",
        "price": "249.00",
        "status": "active",
        "stock_quantity": 6,
        "in_stock": true,
        "variants": [
          { "id": "9a1e…", "sku": "LENA-CZ-S", "size": "S", "color": "Czarny", "stock": 2, "priceOverride": null }
        ]
      }
    ],
    "limit": 100,
    "offset": 0
  }
}

PATCH /stock

Required scope: stock:write

Sets stock for up to 1000 SKUs in one request. Stock is set, not added – a retried request doubles nothing. We subtract units held by orders awaiting payment and by try-on reservations ourselves. The response says how many sizes changed, which SKUs we do not know and which stock values are invalid.

Example

curl -X PATCH "https://www.boutiqverse.com/api/partner/stock" \
  -H "Authorization: Bearer $BOUTIQVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "updates": [ { "sku": "LENA-CZ-S", "stock": 4 }, { "sku": "LENA-CZ-M", "stock": 0 } ] }'

{
  "success": true,
  "data": { "updated": 2, "notFound": [], "invalid": [] }
}

GET /orders

Required scope: orders:read

Orders with your products – only your lines and the state of your parcel. Parameters: since (an ISO date) and limit (1 to 500).

Example

curl "https://www.boutiqverse.com/api/partner/orders?since=2026-10-01T00:00:00Z&limit=100" \
  -H "X-API-Key: $BOUTIQVERSE_API_KEY"

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "c41d…",
        "order_number": "ORD-2026-001234",
        "status": "processing",
        "created_at": "2026-10-28T09:12:44.000Z",
        "shipping_country": "PL",
        "tracking_number": null,
        "carrier": null,
        "items": [
          { "productId": "5f0c8a52-…", "sku": "LENA-CZ-S", "name": "Sukienka Lena", "quantity": 1, "price": "249.00", "size": "S", "color": "Czarny" }
        ]
      }
    ]
  }
}

POST /orders/{id}/ship

Required scope: orders:write

Hands over a tracking number. The parcel becomes shipped exactly as in the panel: the customer gets an email. If the customer withdrew before shipping or the order cannot be shipped, you get a 409 response with an error code.

Example

curl -X POST "https://www.boutiqverse.com/api/partner/orders/c41d…/ship" \
  -H "Authorization: Bearer $BOUTIQVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "trackingNumber": "520000011395200025754312", "carrier": "inpost" }'

{
  "success": true,
  "data": { "trackingNumber": "520000011395200025754312", "trackingUrl": "https://…", "carrier": "inpost" }
}

Errors

An error is JSON with the fields success (false), message and usually code.

401 – no key (API_KEY_REQUIRED) or a wrong or revoked key (API_KEY_INVALID)
403 – the key lacks the required scope (SCOPE_REQUIRED)
404 – no such order, or it is not yours
409 – the order cannot be shipped now
429 – too many requests

Webhooks

Set the address, secret and events in the panel: Settings → Webhooks. We send a POST with JSON to an https address. The X-Butiki-Signature header is the HMAC-SHA256 of the raw request body with your secret (hex), X-Butiki-Event is the event type and X-Butiki-Delivery the delivery id. A delivery succeeds when your server answers with a 2xx code within 15 seconds. Otherwise we try again after a minute, 5 minutes, 30 minutes and 3 hours – up to 5 attempts in total.

order.creatednew order
order.paidorder paid
order.shippedparcel shipped
order.refundedorder refunded
order.cancelledorder cancelled
product.updatedproduct changed – also by the sync with your shop
return.creatednew return or complaint
return.refundedreturn refunded

Example

POST https://twoj-serwer.pl/boutiqverse
Content-Type: application/json
X-Butiki-Event: order.paid
X-Butiki-Delivery: 7b0f…
X-Butiki-Signature: 3f9a…   (HMAC-SHA256, hex)

{ "id": "7b0f…", "type": "order.paid", "payload": { … }, "createdAt": "2026-10-28T09:13:02.000Z" }

Checking the signature

// Node.js: podpis liczony z SUROWEJ tresci zadania
const crypto = require("crypto")

function isFromBoutiqVerse(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(String(signatureHeader || ""))
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Is your platform missing?

Need another method or an integration with another platform? We will add it for free. Write to us