Quickstart

There is no sandbox

Every request acts on your real Bigblue account. A product you create appears in your catalogue, and an order can be picked, packed and shipped by the warehouse. Use a test integration with automatic fulfillment turned off, and cancel test orders when you're done.

Create an API key

In the Bigblue app, create an integration and copy its API key. The key is shown once. Afterwards the app only shows its last four characters.

Each integration has two settings that apply to the orders you create with its key:

Primary warehouse: the warehouse orders ship from by default. You can choose another warehouse per order with auto_fulfill_warehouse.
Auto-fulfill orders: whether orders go to the warehouse automatically. This can only be changed in the app. Turn it off for testing.

Store the key in an environment variable:

export BIGBLUE_API_KEY="your-api-key"

List your inventory

ListInventories only reads data, so it's a safe first request.

curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListInventories \
  -H "Authorization: Bearer $BIGBLUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 5}'

On a new account with no stock, the response is an empty object, because empty lists are left out:

200: no stock yet

{}

With stock, you get one row per product and warehouse:

200: with stock

{
  "inventories": [
    {
      "product": "BGBL-ESPSRT-SMAL",
      "warehouse": "FR-CDG-001",
      "available": 412,
      "in_warehouse": 430
    }
  ]
}

If the key is missing, you get 401. If it isn't recognized, you get 403:

401

{ "code": "unauthenticated", "msg": "api key must be included" }

403

{ "code": "permission_denied", "msg": "unauthorized" }

Create a product

Products must exist before stock can arrive or orders can ship. Product IDs start with your four-character tenant code. In these examples the tenant code is BGBL: replace it with yours.

curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateProduct \
  -H "Authorization: Bearer $BIGBLUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "id": "BGBL-ESPSRT-SMAL",
      "sku": "ESP-SHIRT-S",
      "name": "Espresso T-shirt, Small",
      "barcode": "3401579800127",
      "value": { "amount": "24.90", "currency": "EUR" },
      "tariff_number": "6109.10",
      "origin_country": "PT"
    }
  }'

See Create product for all fields.

Send stock to a warehouse

Stock arrives through inbound shipments. Tell the warehouse what you're sending with CreateInboundShipment. When the warehouse has received it, the units appear in ListInventories.

Create an order

Send your own 12-character id. If the request fails and you retry it, the retry returns already_exists instead of creating a second order.

curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CreateOrder \
  -H "Authorization: Bearer $BIGBLUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "id": "BGBLTEST0001",
      "external_id": "test-0001",
      "language": "fr",
      "currency": "EUR",
      "shipping_address": {
        "first_name": "Camille",
        "last_name": "Bernard",
        "email": "camille@example.com",
        "line1": "12 rue de Rivoli",
        "city": "Paris",
        "postal": "75004",
        "country": "FR"
      },
      "line_items": [
        {
          "product": "BGBL-ESPSRT-SMAL",
          "quantity": 1,
          "unit_price": "24.90",
          "unit_tax": "4.15"
        }
      ],
      "shipping_price": "4.90"
    }
  }'

To remove a test order, cancel it with CancelOrder before the warehouse starts picking it:

curl -X POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/CancelOrder \
  -H "Authorization: Bearer $BIGBLUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "BGBLTEST0001", "reason": "Test order"}'

Set up webhooks

Instead of polling for stock and order status changes, receive them as webhooks. See Webhooks.