BigblueDevelopers

Orders

Orders ask Bigblue to pick, pack and ship items to a customer.

Operations

Create order

Send an order to Bigblue for fulfillment.

Update order

Change an order before it's picked.

Get order

Get an order with its status and tracking.

List orders

List orders by country, date or integration.

Cancel order

Cancel an order before it ships.

List order tickets

List the support tickets for an order.

Order statuses

What each status means.

The Order object

idstring
Bigblue order ID.
Pattern^([A-Za-z0-9]{12})$
external_idstring
Your own order reference.
storestring
The integration that created the order. Read-only.
submit_timestring
When Bigblue received the order, RFC 3339 UTC. Set by Bigblue.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z
languagestring
Language for customer notifications, ISO 639-1.
Exactly 2 characters
currencystring
Currency for all amounts on the order, ISO 4217.
Exactly 3 characters
shipping_addressShippingAddress

Delivery address and customer contact details.

billing_addressBillingAddress

Billing address. Defaults to the shipping address.

line_itemsOrder.LineItem[]
Items ordered. At least one.
shipping_pricestring
Shipping price paid by the customer.
shipping_taxstring
Tax on shipping.
additional_taxstring
Tax not tied to a line item or to shipping.
additional_discountstring
Order-level discount, in addition to line discounts.
totalstring
Order total, calculated by Bigblue. See Prices.
shipping_methodstring
Name of the shipping method the customer chose.
pickup_pointPickupPoint

Pickup point, if the parcel isn't delivered to the address.

statusOrder.Status

Status code and message. Read-only. Not included in the create response.

tracking_numberstring
Tracking number of the most advanced parcel. Read-only.
tracking_urlstring
Tracking page for that parcel. Read-only.
shipped_packagesOrderPackage[]

Contents of each packed parcel. Read-only.

b2bboolean
The order is a B2B shipment.
b2b_fulfillment_instructions_templatestring

B2B instructions template applied to the order.

Up to 32 characters
external_order_urlstring

Link to the order in your system, shown to Bigblue support.

customer_order_idstring

Your customer's purchase order (PO) number, passed to the carrier.

Up to 20 characters

Order.LineItem

productstringrequired
Product or bundle ID.
Pattern^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$
quantityintegerrequired
Units ordered, or bundles for a bundle line. Greater than 0.
Greater than 0
unit_pricestringrequired
Price of one unit.
At least 1 character
unit_taxstringrequired
Tax on one unit.
At least 1 character
discountstring
Total discount for the line, not per unit.
lot_codestring

Pick from this lot. Can't be used with lot_expiration_days_range_rule.

Up to 64 characters
lot_expiration_datestring
Expiry date of the lot set in lot_code.
Date as YYYY-MM-DD
lot_expiration_days_range_ruleLotExpirationDaysRangeRule

Pick from a lot whose remaining shelf life is in this range. Can't be used with lot_code.

lot_expiration_timestring
Use lot_expiration_date instead.

LotExpirationDaysRangeRule

minimum_days_to_expirationinteger

Minimum days until the lot expires. 0 means no minimum.

maximum_days_to_expirationinteger

Maximum days until the lot expires. 0 means no maximum.

For example, set minimum_days_to_expiration to 120 for a B2B customer that needs at least 120 days of shelf life.

ShippingAddress

first_namestring
Customer's first name.
Up to 38 characters
last_namestring
Customer's last name.
Up to 38 characters
companystring
Company name.
Up to 38 characters
phonestring
Phone number. Some carriers need it for delivery updates.
Up to 32 characters
emailstring
Email for shipping notifications.
Up to 128 characters
line1stringrequired
Street address.
1–38 characters
line2string
Address line 2.
Up to 38 characters
line3string
Address line 3.
Up to 38 characters
line4string
Address line 4.
Up to 38 characters
citystringrequired
City.
1–38 characters
postalstring
Postal code.
Up to 12 characters
statestring
State or province.
Up to 38 characters
countrystringrequired
ISO 3166-1 alpha-2.
Exactly 2 characters

Values longer than these limits are rejected, not shortened.

BillingAddress

Same fields as ShippingAddress without phone. All fields are optional. Leave the object out to use the shipping address.

PickupPoint

idstringrequired
The carrier's pickup point ID.
2–12 characters
display_namestring
Name shown to the customer.
Up to 64 characters
postalstring
Postal code.
Up to 12 characters
statestring
State or province.
Up to 38 characters
countrystringrequired
ISO 3166-1 alpha-2.
Exactly 2 characters
carrier_servicestringrequired

Bigblue carrier service for the pickup point. If it doesn't match the point, fulfillment fails.

5–32 characters

OrderPackage

Read-only. Describes a packed parcel.

idstring
Package ID.
tracking_numberstring
Tracking number.
weightinteger
Weight in grams.
itemsOrderPackage.Item[]
Contents.

OrderPackage.Item

productstring
Product ID.
Pattern^[A-Za-z0-9]{4}(BU)?-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$
quantityinteger
Units in the package.
lot_codestring
Lot the units came from.
Up to 64 characters
lot_expiration_datestring
Lot expiry date, YYYY-MM-DD.
Date as YYYY-MM-DD
lot_expiration_timestring
Use lot_expiration_date instead.

A bundle line stays a bundle in line_items. Its components are listed in shipped_packages[].items.

Prices

Prices are decimal strings in the order's currency. unit_price doesn't include tax: tax is sent separately in unit_tax, shipping_tax and additional_tax.

Bigblue calculates the total:

total = sum(unit_price × quantity)
      + shipping_price
      + shipping_tax + additional_tax + sum(unit_tax × quantity)
      − additional_discount − sum(discount)

A line's discount is the total for that line, not per unit. The total is never below 0.

Bigblue stores tax and discount as single amounts. When you read an order, shipping_tax and additional_tax are split out again. If the order was edited in the Bigblue app and the amounts no longer add up, the difference is returned as additional_tax and shipping_tax is "0".

Automatic fulfillment

The integration of your API key decides whether orders go to the warehouse automatically. See Authentication. When it's on, the order ships from the integration's primary warehouse. The auto_fulfill_* fields can change the warehouse, priority and timing for one order. When it's off, those fields are ignored.

Reading orders

GetOrder and ListOrders return the status, packages and tracking. CreateOrder doesn't, because they don't exist yet.

List allocation inventories

Get the stock allocated to each sales channel in a warehouse.

Order statuses

The status codes an order can have.

On this page

OperationsThe Order objectOrder.LineItemLotExpirationDaysRangeRuleShippingAddressBillingAddressPickupPointOrderPackageOrderPackage.ItemPricesAutomatic fulfillmentReading orders