Create order · Bigblue Developers

POST/bigblue.storeapi.v1.PublicAPI/CreateOrder

Creates an order. If you don't send an id, Bigblue generates one. Send your own id so that retries can't create duplicates.

The response doesn't include a status, packages or tracking yet. Use GetOrder to read them later.

Request body

orderOrderFormrequired

The order to create.

force_merge_line_itemsbooleandefault false

Merge lines with the same product or bundle into one line.

OrderForm

shipping_addressShippingAddressrequired

Delivery address. Needs line1, city and country.

line_itemsOrder.LineItem[]required

At least one line. Products or bundles.

At least 1 item

shipping_pricestringrequired

Shipping price. Send "0" for free shipping.

At least 1 character

currencystringrequired

ISO 4217 code.

Exactly 3 characters

languagestringrequired

ISO 639-1 code for customer notifications.

Exactly 2 characters

idstring

Your own order ID. Generated if empty.

Pattern^([A-Za-z0-9]{12}|)$

external_idstring

Your own order reference. To find the order by it later, use the external_order filter on ListTrackings.

shipping_taxstring

Tax on shipping.

additional_taxstring

Tax not tied to a line or to shipping.

additional_discountstring

Order-level discount.

shipping_methodstring

Name of the shipping method the customer chose. Shown in the app.

billing_addressBillingAddress

Defaults to the shipping address.

pickup_pointPickupPoint

Deliver to a pickup point. Needs id, country and carrier_service.

b2bbooleandefault false

Mark the order as a B2B shipment.

b2b_fulfillment_instructions_templatestring

B2B instructions template set up in the Bigblue app. Requires b2b: true.

Up to 32 characters

external_order_urlstring

Link to the order in your system.

customer_order_idstring

Your customer's purchase order (PO) number. Up to 20 ASCII characters. Passed to the carrier with the shipment.

Up to 20 characters

auto_fulfill_warehousestring

Ship from this warehouse instead of the integration's primary warehouse.

Pattern^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$

auto_fulfill_reservation_priorityFulfillmentPrioritydefault FULFILLMENT_PRIORITY_UNSPECIFIED

FULFILLMENT_PRIORITY_LOW, FULFILLMENT_PRIORITY_NORMAL or FULFILLMENT_PRIORITY_HIGH.

auto_fulfill_schedule_timestring

Don't fulfill before this time, RFC 3339 UTC.

RFC 3339 in UTC, for example 2026-03-14T09:30:00Z

auto_fulfill_schedule_holdbooleandefault false

Hold the order until you release it. Overrides auto_fulfill_schedule_time.

auto_fulfill_* fields need automatic fulfillment

These fields only apply when Auto-fulfill orders is on for your API key's integration. Otherwise they're ignored and the order waits until it's sent from the app.

B2B templates need b2b: true

Sending b2b_fulfillment_instructions_template without b2b: true fails with invalid_argument.

PO numbers must be ASCII

A customer_order_id longer than 20 characters fails with invalid_argument. One with accented or other non-ASCII characters is accepted, but fails Bigblue's order checks: the order isn't prepared until you correct it with UpdateOrder.

Choosing a lot

You can set lot_code or lot_expiration_days_range_rule on a line, but not both. If you set neither, the warehouse picks the lot that expires first.

Responses

200The order was created.

orderOrder

The new order with id, store and submit_time. Doesn't include status, shipped_packages or tracking.

400A field is invalid, an amount or currency can't be parsed, or a rule isn't met.

{
  "code": "invalid_argument",
  "msg": "order.shipping_address.line1 value length must be at least 1 characters",
  "meta": { "argument": "order.shipping_address.line1" }
}

404A line references a product or bundle that doesn't exist.

{ "code": "not_found", "msg": "product BGBL-ESPSRT-XLRG not found" }

409An order with this ID already exists.

{ "code": "already_exists", "msg": "order BGBL0K3M9XQ2 already exists" }

If you're retrying with your own ID, the first request succeeded.

POST/bigblue.storeapi.v1.PublicAPI/CreateOrder

Request: home delivery

{
  "order": {
    "id": "BGBL0K3M9XQ2",
    "external_id": "web-10231",
    "language": "fr",
    "currency": "EUR",
    "shipping_address": {
      "first_name": "Camille",
      "last_name": "Bernard",
      "email": "camille@example.com",
      "phone": "+33612345678",
      "line1": "12 rue de Rivoli",
      "city": "Paris",
      "postal": "75004",
      "country": "FR"
    },
    "line_items": [
      {
        "product": "BGBL-ESPSRT-SMAL",
        "quantity": 2,
        "unit_price": "24.90",
        "unit_tax": "4.15",
        "discount": "5.00"
      }
    ],
    "shipping_price": "4.90",
    "shipping_tax": "0.82",
    "shipping_method": "Standard"
  }
}

200

{
  "order": {
    "id": "BGBL0K3M9XQ2",
    "external_id": "web-10231",
    "store": "i_bgbl0001",
    "submit_time": "2026-03-14T09:30:00Z",
    "language": "fr",
    "currency": "EUR",
    "shipping_address": {
      "first_name": "Camille",
      "last_name": "Bernard",
      "email": "camille@example.com",
      "phone": "+33612345678",
      "line1": "12 rue de Rivoli",
      "city": "Paris",
      "postal": "75004",
      "country": "FR"
    },
    "line_items": [
      {
        "product": "BGBL-ESPSRT-SMAL",
        "quantity": 2,
        "unit_price": "24.9",
        "unit_tax": "4.15",
        "discount": "5"
      }
    ],
    "shipping_price": "4.9",
    "shipping_tax": "0.82",
    "additional_tax": "0",
    "additional_discount": "0",
    "total": "58.82",
    "shipping_method": "Standard"
  }
}

Total: 2 × 24.90 + 4.90 shipping + 9.12 tax (2 × 4.15 + 0.82) − 5.00 discount = 58.82. Amounts come back without trailing zeros.

Request: pickup point

{
  "order": {
    "external_id": "web-10232",
    "language": "fr",
    "currency": "EUR",
    "shipping_address": {
      "first_name": "Camille",
      "last_name": "Bernard",
      "line1": "12 rue de Rivoli",
      "city": "Paris",
      "country": "FR"
    },
    "pickup_point": {
      "id": "056321",
      "display_name": "Tabac de la Bastille",
      "postal": "75011",
      "country": "FR",
      "carrier_service": "mondialrelay-fr-pp"
    },
    "line_items": [
      {
        "product": "BGBL-ESPSRT-SMAL",
        "quantity": 1,
        "unit_price": "24.90",
        "unit_tax": "4.15"
      }
    ],
    "shipping_price": "3.50"
  }
}

Request: B2B with minimum shelf life

{
  "order": {
    "external_id": "po-88120",
    "customer_order_id": "PO-4500018812",
    "language": "en",
    "currency": "EUR",
    "b2b": true,
    "b2b_fulfillment_instructions_template": "tpl_retail_eu",
    "shipping_address": {
      "company": "Retail Supply Chain",
      "line1": "Route de Paris",
      "city": "Vitry-sur-Seine",
      "postal": "94400",
      "country": "FR"
    },
    "line_items": [
      {
        "product": "BGBL-COFBEA-1KGX",
        "quantity": 480,
        "unit_price": "11.20",
        "unit_tax": "0.62",
        "lot_expiration_days_range_rule": {
          "minimum_days_to_expiration": 120
        }
      }
    ],
    "shipping_price": "0",
    "auto_fulfill_warehouse": "FR-CDG-001",
    "auto_fulfill_reservation_priority": "FULFILLMENT_PRIORITY_HIGH"
  }
}