NAV Navbar
go javascript
  • Introduction
  • Authentication
  • Orders
  • Inventory
  • Introduction

    Welcome to bigblue's API! You can access our API endpoints to:

    Get statuses and tracking information about one or several orders
    Get all details about one or several orders
    Create a new order
    Check your inventory

    The API is provided to you by bigblue:

    We also have some specific language snippets to make integration easier. You can switch the programming language of the examples with the tabs in the top right. Snippets are provided in Go and Node.

    Authentication

    Bigblue API uses a token-based authentication scheme inside a custom HTTP header: X-Bigblue-Token: <insert your API token>. Have a look at the examples to see how it's done in your favorite language.

    Orders

    orders.statuses method

    The orders.statuses method lets you retrieve orders statuses, packages and tracking information from a list of orders provided.

    Example: GET /orders.statuses

    import (
      "net/http"
      "strings"
    )
    
    client: &http.Client{
        Timeout: 20 * time.Second,
    }
    
    req, err := http.NewRequest("GET", "https://api.beta.bigblue.co/v1/orders.statuses", nil)
    if err != nil {
      // deal with err
    }
    
    req.Header.Set("x-bigblue-token", "MyAPIToken123")
    
    orderIDs := [...]string{"BBLE825D4A8X","BBLE450DY7TA"}
    
    q := req.URL.Query()
    q.Add("ids", strings.Join(orderIDs,","))
    req.URL.RawQuery = q.Encode()
    
    resp, err := client.Do(req)
    if err != nil {
      // deal with err
    }
    
    type OrdersStatusesResponse struct {
        Orders []*OrderStatus `json:"orders"`
    }
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
      // deal with err
    }
    
    osr := new(OrdersStatusesResponse)
    err = json.Unmarshal(body, osr)
    if err != nil {
        // deal with err
    }
    
    // use osr.Orders !
    
    
    const axios = require('axios')
    
    var orders = ['BBLE825D4A8X', 'BBLE450DY7TA']
    
    class Bigblue {
      constructor(token) {
        this.client = axios.create({
          baseURL: 'https://api.beta.bigblue.co/',
          timeout: 10000,
          headers: {
            'x-bigblue-token': token
          }
        })
      }
    
      async getOrdersStatuses(orders) {
        const resp = await this.client({
          method: 'get',
          url: '/orders.statuses',
          params: {
            ids: orders.join(',')
          }
        })
        if (resp.status !== 200) {
          throw `error: ${resp.statusText}`
        }
        return resp.data.orders
      }
    }
    

    Endpoint

    https://api.beta.bigblue.co/v1/orders.statuses
    https://api.beta.bigblue.co/v1/orders.statuses

    Arguments

    Requests to this endpoint expect an authentication header and:

    Key Type Default Description
    ids []string [] Bigblue order IDs

    Example of POST body

    {
      "ids": ["BBLE825D4A8X", "BBLE450DY7TA"]
    }
    

    Response status codes

    Code Description
    200 Ok
    401 Bad request: orders IDs are missing

    Response schema

    Example: /orders.statuses response

    {
      "orders": [
        {   
          "id": "BBLE825D4A8X",
          "status": "In Transit",
          "statusMessage" : "delivery time scheduled",
          "packages": [
            {
              "id": "package1",
              "trackingNumber": "TRACK789",
              "trackingURL": "https://trackingmypackage.com/track789",
              "status": "Delivered",
              "statusMessage": "delivered",
              "eta": "2017-05-25T18:00:00Z",
              "updatedAt":"2018-06-25T18:25:43Z"
            },
            {
              "id": "package2",
              "trackingNumber": "TRACK790",
              "trackingURL": "https://trackingmypackage.com/track790",
              "status": "Out For Delivery",
              "statusMessage": "expected delivery on april, 27th",
              "eta": "2017-05-26T17:00:00Z",
              "updatedAt":"2018-06-25T18:25:43Z"
            }
          ] 
        }
      ]
    }
    
    Main response Type Description
    orders []OrderStatus A list of objects containing status information of valid orders.

    OrderStatus attributes

    Attribute Type Description
    id string Bigblue order ID.
    status string Global status of the order. See possible values.
    statusMessage string Additional status information.
    packages []PackageStatus A list of PackageStatus for this order.

    PackageStatus attributes

    Attribute Type Description
    id string Bigblue package ID.
    trackingNumber string Package tracking number provided by the transporter.
    trackingURL string URL where package tracking is available.
    status string See possible statuses.
    statusMessage string Additional status information.
    eta RFC 3339 date string Package Estimated Time of Arrival.
    updatedAt RFC 3339 date string Time of last update.

    orders.list method

    The orders.list method lets you retrieve detailed information of multiple orders.

    Example: GET /orders.list

    import (
      "net/http"
      "strings"
    )
    
    client: &http.Client{
        Timeout: 20 * time.Second,
    }
    
    req, err := http.NewRequest("GET", "https://api.beta.bigblue.co/v1/orders.list", nil)
    if err != nil {
      // deal with err
    }
    
    req.Header.Set("x-bigblue-token", "MyAPIToken123")
    
    orderIDs := [...]string{"BBLE825D4A8X","BBLE450DY7TA"}
    
    q := req.URL.Query()
    q.Add("ids", strings.Join(orderIDs,","))
    req.URL.RawQuery = q.Encode()
    
    resp, err := client.Do(req)
    if err != nil {
      // deal with err
    }
    
    type OrdersListResponse struct {
        Orders []*Order `json:"orders"`
    }
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
      // deal with err
    }
    
    odr := new(OrdersDetailsResponse)
    err = json.Unmarshal(body, odr)
    if err != nil {
        // deal with err
    }
    
    // use odr.Orders !
    
    const axios = require('axios')
    
    var orders = ['BBLE825D4A8X', 'BBLE450DY7TA']
    
    class Bigblue {
      constructor(token) {
        this.client = axios.create({
            baseURL: 'https://api.beta.bigblue.co/',
            timeout: 10000,
            headers: {
              'x-bigblue-token': token
            }
        })
      }
    
      async getOrdersStatuses(orders) {
        const resp = await this.client({
          method: 'get',
          url: '/orders.list',
          params: {
            ids: orders.join(',')
          }
        })
        if (resp.status !== 200) {
          throw `error: ${resp.statusText}`
        }
        return resp.data.orders
      }
    }
    

    Endpoint

    https://api.beta.bigblue.co/v1/orders.list
    https://api.beta.bigblue.co/v1/orders.list

    Arguments

    Requests to this endpoint expect an authentication header and:

    Key Type Default Description
    ids []string [] List of bigblue's order IDs

    Example of POST body

    {
      "ids": ["BBLE825D4A8X", "BBLE450DY7TA"]
    }
    

    Response status codes

    Code Description
    200 ok
    401 Bad request: orders IDs are missing

    Response schema

    Example: /orders.list response

    {
      "orders": [
        {
        "id": "BBLE825D4A8X",
        "externalId": "yourorderid5",
        "shippingAddress": {
          "firstName": "Jackie",
          "lastName": "Chan",
          "fullName": "Jackie Chan",
          "company": "bigblue",
          "phone": "0610112131",
          "email": "jackie@mail.com",
          "line1": "Appartement 123",
          "line2": "RESIDENCE DES BOSQUETS",
          "line3": "10 RUE DE LA LIBERTE",
          "line4": "Lieu dit AMAREINS"
          "postalCode": "99123",
          "city": "VILLENOUVELLE",
          "state": "Ile de France",
          "country": "FR"},
        "billingAddress": {
          "firstName": "Jackie",
          "lastName": "Chan",
          "fullName": "Jackie Chan",
          "company": "bigblue",
          "phone": "0610112131",
          "email": "jackie@mail.com",
          "line1": "Appartement 123",
          "line2": "RESIDENCE DES BOSQUETS",
          "line3": "10 RUE DE LA LIBERTE",
          "line4": "Lieu dit AMAREINS"
          "postalCode": "99123",
          "city": "VILLENOUVELLE",
          "state": "Ile de France",
          "country": "FR"},
        "orderDate" : "2017-04-23T08:52:21Z",
        "lineItems": [
          {
            "product": "BBLE-COOL25-BS89",
            "quantity": 3
          },
          {
            "product": "BBLE-COOL25-BS90",
            "quantity": 2
          }
        ],
        "warehouse": "EUGRMN001",
        "carrier": "CHRONO24REL",
        "price": 7040,
        "shippingPrice": 250,
        "tax": 640,
        "discount": 0,
        "currency": "EUR",
        "language": "FR",
        "status": "In Transit",
        "statusMessage" : "delivery time scheduled",
        "packages": [
          {
            "id": "BBLE825D4A8X51",
            "order": "BBLE825D4A8X",
            "trackingNumber": "TRACK789",
            "trackingURL": "https://trackingmypackage.com/track789",
            "status": "Delivered",
            "statusMessage": "delivered",
            "eta": "2017-05-25T17:00:00Z",
            "length": 80,
            "height": 40,
            "width": 65,
            "weight": 5500,
            "lineItems": [
              {
                "product": "BBLE-COOL25-BS89",
                "quantity": 3
              }
            ],
            "updatedAt":"2018-06-25T18:25:43Z"
          },
          {
            "id": "package2",
            "order": "order5",
            "trackingNumber": "track787",
            "trackingURL": "https://trackingmypackage.com/track787",
            "status": "out for delivery",
            "statusMessage": "expected delivery on april, 26th",
            "eta": "2017-05-26T14:00:00Z",
            "length": 60,
            "height": 20,
            "width": 45,
            "weight": 3500,
            "lineItems": [
              {
                "product": "BBLE-COOL25-BS90",
                "quantity": 2
              }
            ],
            "updatedAt":"2018-06-25T18:25:43Z"
          }
        ], 
        "attachedDocs" : [
          {
            "name": "delivery note 3",
            "type": "DELINOTE",
            "url": "https://mydeliverynotedoc.com/dn0012"
          }
        ],
        "linkedOrders" : [
          "BBLE825D4A8Y"]
        }
      ]
    }
    

    Main response

    Attribute Type Description
    orders []Order A list of objects containing orders information of valid orders.

    Order attributes

    Attribute Type Description
    id string Bigblue order ID.
    externalId string Your internal ID related to this order.
    shippingAddress Address Shipping Address
    billingAddress Address Billing Address
    lineItems []LineItem Order lines items (set of products and quantities)
    orderDate RFC 3339 date string Order creation date.
    warehouse string Code of the warehouse you want the order to be fulfilled from. Codes are provided by Bigblue.
    carrier string Bigblue carrier service code
    price integer Total order billing price, including taxes, in cents (e.g. "$120.58" -> 12058)
    shippingPrice integer Shipping price (billed to the client), including taxes, in cents (e.g. "$4.58" -> 458)
    tax integer Sales tax percentage, in cents (e.g. "9.05%" -> 905)
    discount integer Order discount amount, in cents (e.g. "$7.20" -> 720)
    currency string Capitalized ISO 4217 currency code
    language string Capitalized ISO 639-1 language code
    status string Global status of the order. See the list of statuses.
    statusMessage string Additional order status information.
    packages []Package Set of packages fulfilled for this order.
    attachedDocs []AttachedDoc Documents attached to the order.
    linkedOrders []string List of bigblue order IDs linked to this order (e.g. in case items are leaving from different warehouses).

    Address attributes

    Attribute Type Description
    firstName string Recipient's first name, if available.
    lastName string Recipient's last name, if available.
    fullName string Recipient's full name.
    company string Name of the recipient's company, if needed.
    phone string Recipient's phone number.
    email string Recipient's email.
    line1 string First line of address.
    line2 string Second line of address.
    line3 string Third line of address.
    line4 string Fourth line of address.
    postalCode string Postal code (5 characters for France)
    city string Destination city.
    state string State name, if applies.
    country string ISO 3166-1 alpha-2 country code of destination.

    LineItem attributes

    Attribute Type Description
    product string Product's SKU.
    quantity integer Product quantity.

    Package attributes

    Attribute Type Description
    id string Bigblue package ID.
    order string Bigblue corresponding order ID.
    trackingNumber string Package tracking number provided by the transporter.
    trackingURL string URL where package tracking is available.
    status string Package status. The list of statuses is available here.
    statusMessage string Additional status information.
    eta RFC 3339 date string Package Estimated Time of Arrival, if available.
    length integer Package height, in millimeters, if available.
    height integer Package height, in millimeters, if available.
    width integer Package height, in millimeters, if available.
    weight integer Package weight, in grams.
    updatedAt RFC 3339 date string Time of last update.

    AttachedDoc attributes

    Attribute Type Description
    name string Name of the document provided.
    type string Document type.
    url string URL at which the document can be found.

    orders.create method

    The orders.create method lets you create an order to be fulfilled.

    Endpoint

    https://api.beta.bigblue.co/v1/orders.create

    This endpoint expects an order in JSON format with the listed attributes.

    Example of POST body

    {
      "externalId": "yourOrderId6",
      "shippingAddress": {
        "firstName": "Jackie", 
        "lastName": "Chan",
        "fullName": "Jackie Chan",
        "company": "bigblue", // optional
        "phone": "0610112131", // optional
        "email": "jackie@mail.com",
        "line1": "Appartement 123",
        "line2": "RESIDENCE DES BOSQUETS", // optional
        "line3": "10 RUE DE LA LIBERTE",// optional
        "line4": "Lieu dit AMAREINS" // optional
        "postalCode": "99123",
        "city": "VILLENOUVELLE",
        "state": "Ile de France", // optional
        "country": "FRANCE"},
      "billingAddress"{
        "firstName": "Jackie",
        "lastName": "Chan",
        "fullName": "Jackie Chan",
        "company": "bigblue", // optional
        "phone": "0610112131", // optional
        "email": "jackie@mail.com",
        "line1": "Appartement 123", // optional
        "line2": "RESIDENCE DES BOSQUETS", // optional
        "line3": "10 RUE DE LA LIBERTE",
        "line4": "Lieu dit AMAREINS" // optional
        "postalCode": "99123",
        "city": "VILLENOUVELLE",
        "state": "Ile de France", // optional
        "country": "FRANCE"},
      "lineItems": [
        {
          "product": "YOUC-COOL26-XX72",
          "quantity": 5}],
      "warehouse": "EUGRMN001",
      "carrier": "CHRONO24REL",
      "price": 70000,
      "tax": 7000,
      "discount":500,
      "currency": "EUR",
      "language": "EN", //optional
      "attachedDocs" : [ // optional
        {
          "name": "Client Invoice",
          "type": "INVOICE0",
          "url": "https://mycustomclearancedoc.com/beautifulinvoice"
        }],
    }
    

    Request

    Required attributes need to be in the request. Others are optional.

    Order attributes

    Attribute Required Type Description
    externalId
    string Your order ID. Bigblue order ID will be provided as a response to this request.
    shippingAddress
    Address Shipping Address
    billingAddress Address Optional: if empty, billing address will be the shipping address.
    []lineItem
    LineItems List of items in the order.
    warehouse
    string Code of the warehouse you want the order to be fulfilled from. Codes are provided by Bigblue.
    carrier
    string Bigblue carrier service code
    price
    integer Total order billing price, in cents (e.g. "$120.58" -> 12058)
    shippingPrice
    integer Shipping price (billed to the client), in cents (e.g. "$4.58" -> 458)
    tax
    integer Sales tax percentage, in cents (e.g. "9.05%" -> 905)
    discount
    integer Order discount amount, in cents (e.g. "$7.20" -> 720)
    currency
    string Capitalized ISO 4217 currency code.
    language string Capitalized ISO 639-1 language code.
    attachedDocs []AttachedDoc List of documents attached to the order

    Address attributes

    Attribute Required? Type Description
    firstName
    string Recipient's first name. If not available, please provide at least the full name.
    lastName
    string Recipient's last name. If not available, please provide at least the full name.
    fullName
    string 38 characters MAX. Recipient's full name. Only use if the fullName is different from "first name + last name"
    company string 38 characters MAX. Name of the recipient's company, if needed.
    phone string Optional but strongly advised. Recipient's phone number. Will be used by the transporter, to contact the recipient.
    email
    string Recipient's email address.
    line1
    string 38 characters MAX - First line of address.
    line2 string
    38 characters MAX - Second line of address, if necessary.
    line3 string 38 characters MAX - Third line of address, if necessary.
    line4 string
    38 characters MAX - Fourth line of address, if necessary.
    postalCode
    string Postal code (5 characters in France)
    city
    string Destination city.
    state string Destination state, if applies.
    country
    string Capitalized ISO 3166-1 alpha-2 country code.

    LineItem attributes

    Attribute Required? Type Description
    product
    string Product's SKU.
    quantity
    integer Product's quantity.

    AttachedDoc attributes

    Attribute Type Description
    name string Name you want to give to the document.
    type integer Document type code. The list of document types codes is available here.
    url string URL where the document is available

    Response status codes

    Code Description
    200 Order has not been created. The reason is given in the response body.
    201 Order was successfully created.
    401 Bad request

    Response schema

    Main response attributes Type Description
    id string Your order ID.

    Example: /orders.create response

    {
      "id": "BBLE825D4A8X"
    }
    

    Carrier services codes

    Carrier Code
    Colissimo Expert COLIOEXPRT
    Colissimo Access COLIOACCSS
    Chronopost Europe CHRONEUROP
    Ups Saver UPSEUSAVER
    La Poste - Lettre Suivie LAPOSLETSU

    Document types

    Name Type
    Delivery Note DELINOTE
    Invoice INVOICE0
    Return Note RETUNOTE
    Return Label RETULABL
    Gift Card GIFTCARD

    Gift cards are not yet supported.

    Orders statuses

    Message Description
    On hold unreserved Order is on hold for future fulfillment but items are not reserved.
    On hold Order is on hold for future fulfillment. All items are reserved.
    Back order Order cannot be fulfilled as inventory level for the item is too low.
    Pending Order is being processed by our system.
    Transmitted Order preparation instructions have been transmitted to the warehouse.
    In preparation Order's items are being prepared at the warehouse.
    Prepared Order has been prepared and waiting to ship.
    Partially shipped µPart of the order's packages have shipped from the warehouse.
    Shipped The order has shipped.
    Partially delivered Some of the order's items have been delivered.
    Delivered All order's items have been delivered.
    Cancelled Order has been cancelled.
    Error There was an error while processing the order.

    Package statuses

    Message Description
    Prepared Package has been prepared by the warehouse.
    In transit Package is in transit to the destination.
    Out for delivery Package came out of the last hub, for last mile delivery.
    Delivered Package was successfully delivered.
    Attempt failed Carrier failed to deliver the package.
    Exception There was an exception.
    Expired Package has expired.

    Inventory

    The inventory.list method lets you comprehensively retrieve your inventory details, for all your products and across all warehouses.

    Endpoint

    https://api.beta.bigblue.co/v1/inventory.list
    https://api.beta.bigblue.co/v1/inventory.list

    Example: GET /inventory.list

    import (
      "net/http"
    )
    
    client: &http.Client{
      Timeout: 20 * time.Second,
    }
    
    req, err := http.NewRequest("GET", "https://api.beta.bigblue.co/v1/inventory.list", nil)
    if err != nil {
       // deal with err
    }
    
    req.Header.Set("x-bigblue-token", "MyAPIToken123")
    
    q := req.URL.Query()
    req.URL.RawQuery = q.Encode()
    
    resp, err := client.Do(req)
    if err != nil {
        // deal with err
    }
    
    type InventoryResponse struct {
        Inventory []*Inventory `json:"inventory"`
    }
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
      // deal with err
    }
    
    ir := new(InventoryResponse)
    err = json.Unmarshal(body, ir)
    if err != nil {
        // deal with err
    }
    
    // use ir.Products !
    
    const axios = require('axios')
    
    class Bigblue {
      constructor(token) {
        this.client = axios.create({
          baseURL: 'https://api.beta.bigblue.co/',
          timeout: 10000,
          headers: {
            'x-bigblue-token': token
          }
        })
      }
    
      async getInventory() {
        const resp = await this.client({
          method: 'get',
          url: '/inventory.list'
        })
        if (resp.status !== 200) {
          throw `error: ${resp.statusText}`
        }
        return resp.data.inventory
      }
    }
    

    Your request to this endpoint only requires an authentication header.

    Response status codes

    Code Description
    200 Ok

    Response data

    Example: /inventory.list response

    [
      {
        "product": "YOUC-COOL26-XX72",
        "warehouse": "EUGRMN001",
        "total": 200,
        "incoming": 100,
        "reserved": 50,
        "damaged": 0
      },
      {
        "product": "YOUC-COOL26-XX73",
        "warehouse": "EUGRMN001",
        "total": 100,
        "incoming": 0,
        "reserved": 20,
        "damaged": 0
      }
    ]
    
    Attribute Type Description
    product string Product's SKU.
    warehouse string Bigblue code of the warehouse where the inventory is located.
    total integer Total number of product's items in the specified warehouse.
    incoming integer Number of items en route to the warehouse that you have decided to make available for selling before it arrives.
    reserved integer Number of items that you have decided to reserve for a specific purpose.
    damaged integer Number of items that have been declared damaged by the warehouse. Those items won't be fulfilled.

    Total quantity available for selling is equal to total + incoming - reserved - damaged