NAV

Introduction

The Booqable API is a RESTful API and as such is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use standard HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application.

Creating an API key

To interact with our API, first, you have to have a means of authentification, here's how to create a shiny new API key.

  1. Go to your account settings page {company-name-here}.booqable.com/account/edit
  2. Name your new key
  3. Click "Create new key"

You can manage your API keys from your account. You can have multiple API keys active at one time.

Contributing

The API is going to be a very important part of our eco system. We've designed the docs in a way every developer is able to contribute to our API. If you find a bug or you have a great suggestion open an issue or pull request on Github. Check our github repository for a readme on how to participate. We love to see your additions!

Endpoint

All API requests need to be directed to the correct company-specific endpoint. The format is as follows:

https://{company_slug}.booqable.com/api/1/

Authentication

Example of an authorized request

curl --request GET \
  --url 'https://company.booqable.com/api/1/customers?api_key=API_KEY_HERE'

You authenticate to the Booqable API by providing on of your API keys in the request. This can be done by appending ?api_key=API_KEY_HERE to the end of your request URL.

Customers

Example of a customer

{
    "customer": {
        "id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
        "updated_at": "2018-01-15T15:27:52.172Z",
        "created_at": "2018-01-15T15:22:27.479Z",
        "legacy_id": null,
        "avatar_url": "https://gravatar.com/avatar/35f5782642e9fa0f6cfff5a552e2ae97.png?d=blank",
        "archived": false,
        "number": 7,
        "name": "Jane Doe",
        "email": "[email protected]",
        "tax_region_id": null,
        "discount_percentage": 0.0,
        "deposit_type": null,
        "deposit_value": 0.0,
        "tags": [
            "buisness"
        ],
        "address1": null,
        "address2": null,
        "city": null,
        "region": null,
        "zipcode": null,
        "country": null,
        "order_count": 2,
        "turnover": "0.0",
        "main_address": null,
        "properties": [],
        "notes": [
            {
                "id": "e4adcf3c-d9af-496a-a4b6-d39544ae91b3",
                "body": "Some note",
                "notable_type": "Customer",
                "notable_id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
                "employee_id": "044b6b43-66f8-4fd2-acf2-0250205b2248",
                "employee": {
                    "id": "044b6b43-66f8-4fd2-acf2-0250205b2248",
                    ...
                }
            }
        ],
        "orders": [
            {
                "id": "a974fe33-a267-4334-9f2b-21b2e4fed852",
                "number": 4,
                "status": "concept",
                "customer_id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
                ...
            }
        ]
    }
}

The Customer object holds all information about a customer. The customer resource has the following attributes:

Field Type Description
id Integer Readonly The identifier of the customer
number Integer Unique The customer's number
name String The name of the customer
email String E-mail address of the customer
avatar_url String Readonly The avatar url
tax_region_id Integer The associated tax region.
orders Array The customer's orders (?)
properties Array The customer's custom properties.
notes Array The customer's notes.
archived Boolean Readonly Whether the customer is archived
created_at DateTime Readonly When the customer was created
updated_at DateTime Readonly When the customer was last updated

Required in bold

List all customers

curl --request GET \
  --url 'https://example.booqable.com/api/1/customers?page=1&per=2&api_key=example_key'

This request returns JSON structured like this:

{
    "customers": [
        {
            "id": "b496c71d-2211-4e27-bf80-3058e5294358",
            ...
        },
        {
            "id": "49785b51-ca29-4fe8-8218-dacbf1d099ff",
            ...
        }
    ],
    "meta": {
        "total_count": 2,
        "facets": {
            "tag_list": {
                "_type": "terms",
                "missing": 2,
                "total": 0,
                "other": 0,
                "terms": []
            }
        }
    }
}

This endpoint retrieves all customers and can paginated

HTTP Request

GET /customers or GET /customers?page=:page&per=:per

Query parameters

Parameter Default Description
page 1 Which page to display
per nil If set it limits the number of customers per page

Meta

The meta object contains metadata about the complete collection (not affected by pagination)

Parameter Description
total_count Total amount of customers
tag_list List of tags related to customers

Create a new customer

Format of request body

{
    "customer": {
        "name": "Jack Doe",
        "email": "[email protected]",
        "properties_attributes": [
            {
                "type": "Property::Address",
        "name": "Main",
        "address1": "Pieter stuyvesantweg 153",
        "address2": "Unit 504",
        "zipcode": "8937AH",
        "city": "Leeuwarden",
        "country": "Netherlands"
            },
      {
        "type": "Property::Phone",
        "name": "Phone",
        "value": "+315812345678"
      }
        ]
    }
}

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/customers' \
  --header 'content-type: application/json' \
  --data '{
    "customer": {
        "name": "Jane Doe",
        "email": "[email protected]",
        "tax_region_id": 1,
        "properties_attributes": [
            {
                "type": "Property::Address",
        "name": "Main",
        "address1": "Pieter stuyvesantweg 153",
        "address2": "Unit 504",
        "zipcode": "8937AH",
        "city": "Leeuwarden",
        "country": "Netherlands"
            },
      {
        "type": "Property::Phone",
        "name": "Phone",
        "value": "+315812345678"
      }
        ]
    }
}'

This request returns JSON structured like this

{
    "customer": {
        "id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
        "name": "Jane Doe",
        "email": "[email protected]",
        ...
    }
}

Creates a new customer with the provided properties

HTTP Request

POST /customers

Required parameters

name

Get a single customer

Get a customer using their id

curl --request GET \
  --url 'https://example.booqable.com/api/1/customers/b496c71d-2211-4e27-bf80-3058e5294358'

Get a customer using their number

curl --request GET \
  --url 'https://example.booqable.com/api/1/customers/1'

This request returns JSON structured like this

{
    "customer": {
        "id": "b496c71d-2211-4e27-bf80-3058e5294358",
        "number": 1,
        "name": "Jane Doe",
        ...
    }
}

This endpoint will retrieve a single customer by id or number

HTTP Request

GET /customers/:id or GET /customers/:number

Update customer

Format of request body

{
    "customer": {
        "name": "John Doe",
    "properties_attributes": [
      {
        "type": "Property::Phone",
        "name": "Phone",
        "value": "+315811111111"
      }
        ]
    }
}

Example request

curl --request PATCH \
  --url https://example.booqable.com/api/1/customers/297f2584-5f6c-475d-919f-f8791aa6a06a \
  --header 'content-type: application/json' \
  --data '{
    "customer": {
        "name": "John Doe",
    "properties_attributes": [
      {
        "type": "Property::Phone",
        "name": "Phone",
        "value": "+315811111111"
      }
        ]
    }
}'

This request returns JSON structured like this

{
    "customer": {
        "id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
        "name": "John Doe",
    "properties": [
      {
        "id": "987bbea0-c6d3-4a6a-b770-746d9bf6b487",
        ...
      }
    ]
        ...
    }
}

Update the details of a customer

HTTP Request

PUT /customers/:id or PATCH /customer/:id

Archive customer

Example request

curl --request DELETE \
  --url 'https://example.booqable.com/api/1/customers/b496c71d-2211-4e27-bf80-3058e5294358/archive'

This request returns JSON structured like this

{
    "customer": {
        "id": "b496c71d-2211-4e27-bf80-3058e5294358",
        "name": "John Doe",
        "archived": true,
    ...
    }
}

Archives a customer hiding it from searches, getting this customer by id will still find it, and it can still be updated

HTTP Request

DELETE /customers/:id/archive

Restore customer

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/customers/b496c71d-2211-4e27-bf80-3058e5294358/restore'

This request returns JSON structured like this

{
    "customer": {
        "id": "b496c71d-2211-4e27-bf80-3058e5294358",
        "name": "John Doe",
        "archived": false,
    ...
    }
}

Restores an archived customer

HTTP Request

POST /customers/:id/restore

Product Groups

Here's an example product group

{
  "product_group": {
    "id": "6107b3cc-03a8-4935-906c-20e2c33db7e0",
    "updated_at": "2018-01-16T14:51:23.917Z",
    "created_at": "2018-01-12T15:58:01.753Z",
    "legacy_id": null,
    "name": "Blackmagic Pocket Cinema Camera",
    "slug": "blackmagic-pocket-cinema-camera-fda66bb8-d3c3-48e8-998a-2ab6b9106713",
    "sku": "BLACKMAGIC_POCKET_CINEMA_CAMERA",
    "lag_time": 1800,
    "lead_time": 360,
    "always_available": false,
    "trackable": true,
    "archived": false,
    "archived_at": null,
    "extra_information": null,
    "search_highlight": null,
    "photo_url": null,
    "description": null,
    "show_in_store": true,
    "base_price_in_cents": 5000,
    "price_wrapper_id": null,
    "price_type": "simple",
    "price_period": "day",
    "tax_category_id": null,
    "flat_fee_price_in_cents": 5000,
    "structure_price_in_cents": 0,
    "deposit_in_cents": 0,
    "products_count": 1,
    "stock_count": 10,
    "has_variations": false,
    "variation_fields": [],
    "stock_item_properties": [],
    "tags": [],
    "base_price_as_decimal": 50.0,
    "flat_fee_price_as_decimal": 50.0,
    "structure_price_as_decimal": 0,
    "deposit_as_decimal": 0,
    "products": [
    ...
    ],
    "properties": [],
    "notes": []
  }
}

Product groups define the kind of products that are available but not individual stock items. A product will always belong to a product group.

Field Type Description
id Integer Readonly The identifier of the product group
name String Name of the product group
sku String SKU of the product group. Only applies when the product group has no variations
lag_time Integer Lag time in seconds
lead_time Integer Lead time in seconds
trackable Boolean Whether the product group has trackable (unique) stock
base_price_in_cents Integer Base price in cents. This is used for price calculation
price_id Integer ID of the associated price structure
price_type String Price setting. Options are: blank, 'simple' or 'structure'
price_period String Only applies when price_type is set to simple. Options are: 'hour', 'day', 'week', 'month' or 'year'
archived Boolean Whether the product group is archived
archived_at DateTime When the product group was archived
quantity Integer Amount of stock
variation_values Array Only applies when the product is a variation. Example: ['128GB', 'Spacegray']
tax_category_id Integer ID of the associated tax category
created_at DateTime Readonly When the product group was created
updated_at DateTime Readonly When the product group was last updated

Required in bold

List all product groups

Example request

curl --request GET \
  --url 'https://example.booqable.com/api/1/product_groups'

This request returns JSON structured like this

{
  "product_groups": [
    {
      "id": "9c27c177-c6b5-4925-b67b-e69053c88399",
      "name": "Arriflex 16SR3",
      ...

    },
    {
      "id": "6107b3cc-03a8-4935-906c-20e2c33db7e0",
      "name": "Blackmagic Pocket Cinema Camera",
      ...
    }
  ],
  "meta": {
    "total_count": 2,
    "facets": {
      "tag_list": {
        "_type": "terms",
        "missing": 2,
        "total": 0,
        "other": 0,
        "terms": []
      },
      "status": {
        "_type": "terms",
        "missing": 0,
        "total": 5,
        "other": 0,
        "terms": [
          {
            "term": "active",
            "count": 2
          },
          {
            "term": "with_stock",
            "count": 1
          },
          {
            "term": "trackable",
            "count": 1
          },
          {
            "term": "bulk",
            "count": 1
          }
        ]
      }
    }
  }
}

This endpoint retrieves all product groups and can paginated

HTTP Request

GET /product_groups or GET /product_groups?per=:per&page=:page

Query parameters

Parameter Default Description
page 1 Which page to display
per nil If set it limits the number of product groups per page

Meta

The meta object contains metadata about the complete collection (not affected by pagination)

Parameter Description
total_count Total amount of product groups
tag_list List of tags and ammount of products tagged
status Info about what kind of tracking mechanism product groups are using and how many are available

Create a new product group

Request body structure

{
    "product_group": {
        "name": "Arriflex 16SR3",
        "sku": "ARRIFLEX_16_SR3",
        "base_price_in_cents": "130000",
        "price_type": "simple",
        "price_period": "day"
    }
}

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/product_groups' \
  --header 'content-type: application/json' \
  --data '{
    "product_group": {
        "name": "Arriflex 16SR3",
        "sku": "ARRIFLEX_16_SR3",
        "base_price_in_cents": "130000",
        "price_type": "simple",
        "price_period": "day"
    }
}'

This request returns JSON structured like this

{
  "product_group": {
    "id": "aff93024-a928-4da7-917a-799ea5d189ae",
    "name": "Arriflex 16SR3",
    "sku": "ARRIFLEX_16_SR3",
    "trackable": false,
    "base_price_in_cents": 130000,
    "price_type": "simple",
    "price_period": "day",
    "base_price_as_decimal": 1300.0,
    "products_count": 1,
    ...
    "products": [
      {
        "id": "9bd04569-8c85-4b01-b0c5-f7070c319bcc",
        "name": "Arriflex 16SR3",
        ...
      }
    ],
    "properties": [],
    "notes": []
  }
}

Creates a new product group with the provided properties

HTTP Request

POST /product_groups

Get a single product group

Example request

curl --request GET \
  --url 'https://example.booqable.com/api/1/product_groups/6107b3cc-03a8-4935-906c-20e2c33db7e0'

This request returns JSON structured like this

{
  "product_group": {
    "id": "6107b3cc-03a8-4935-906c-20e2c33db7e0",
    "name": "Blackmagic Pocket Cinema Camera",
    ...
    "products": [
      {
        "id": "c560ea83-5231-4052-831e-c26db0121c1b",
        "name": "Blackmagic Pocket Cinema Camera",
        "quantity": 10,
        "product_group_id": "6107b3cc-03a8-4935-906c-20e2c33db7e0",
        ...
        "stock_items": [
          {
            "id": "38b8a49f-9e39-4bf3-8336-2df392b1bee8",
            "identifier": "10",
            "item_id": "c560ea83-5231-4052-831e-c26db0121c1b",
            "status": "available",
            ...
          },
          {
            "id": "2bfbbf9f-4736-45eb-bf57-22b5355c41c8",
            "identifier": "9",
            "item_id": "c560ea83-5231-4052-831e-c26db0121c1b",
            "status": "available",
            ...
          },
          ...
        ]
      }
    ],
    "properties": [],
    "notes": []
  }
}

This endpoint will retrieve a single product group by id

HTTP Request

GET /product_groups/:id

Update product group

Request body structure

{
    "product_group": {
        "sku": "BM_POCKET_CINEMA_CAMERA"
    }
}

Example request

curl --request PATCH \
  --url 'https://example.booqable.com/api/1/product_groups/6107b3cc-03a8-4935-906c-20e2c33db7e0' \
  --header 'content-type: application/json' \
  --cookie 'request_method=GET; _rental_api_session=NFBoY2IxclJiQTBjdzZ4aWkxUmFUNzNZYjlXckJPbU9sUUh2OTVlS2c4NElRMW4wRGFMYlE5Mnozam9JMm9GSUhlVU9HYjNudFJJS3NhSzNGUDdaYVQzZk5tWjVwUmdQRXlvaGZXVDRXb2hmYWVIZ0t1eVYyaU54b0w3bXJ5Tm9mK0lseWhSOTZ0L28yU1pkOUYrbVdWUW5nbDNHQlU3K0d1RHdPdVJqbGdRZERwWVhsTGYyNlpsSHlxclBVck5zeVp1NXJ0N0g5eHNtaFljeDh1ekp4MWxYd3QxZTlKM2xXMFUxRkx5N1NRTkVVQjB0RnduaGFzOTNlSmJQYkYzcVdxMmRWWFVpbCsrSldxcEY4ZWJPaWM0VjRpQnZVMisyQTlEWVhjc3kxQ0Q5N1R5SFF6eSs1R2lDdjBzVDduNVJ4ejJ1eWJ5STFFdzVNWTBrQTJvSW02c3ZralRockQ0bWRUZ3RQdXBHMVdJPS0tNVhVTXY1RGthZEYxSXBBOEtmN0tiZz09--620dd5ead23e2e80caa59daed438a2e1f502797c' \
  --data '{
    "product_group": {
        "sku": "BM_POCKET_CINEMA_CAMERA"
    }
}'

Update the properties of a product group

HTTP Request

PUT /product_groups/:id or PATH /product_groups/:id

Archive product group

Example request

curl --request DELETE \
  --url 'https://example.booqable.com/api/1/product_groups/6107b3cc-03a8-4935-906c-20e2c33db7e0/archive'

Archives a product group

HTTP Request

DELETE /product_groups/:id/archive

Restore product group

Example request

curl --request POST \
  --url 'https://company.booqable.com/api/1/product_groups/6107b3cc-03a8-4935-906c-20e2c33db7e0/restore'

HTTP Request

POST /product_groups/:id/restore

Check availability

Example request

curl --request GET \
  --url 'https://company.booqable.com/api/1/products/23b6445d-c846-404b-8628-acb9023d8e5c/availability?till=01-02-2018&from=01-01-2018

This request returns JSON structured like this

{ "available": 5,
  "needed": 0,
  "plannable": 5,
  "planned": 0,
  "stock_count": 5
}

Provides an availability overview of the specified product in the provided timeframe

HTTP Request

GET /products/:product_id/availablility/?from=:from&till=:till

Query parameters

Parameter Description Available options
from Start date
till End date

Required in bold

Show product pricing structures

Example request

curl --request GET \
  --url 'https://example.booqable.com/api/1/products/c560ea83-5231-4052-831e-c26db0121c1b/prices'

This request returns JSON structured like this

{
  "price_structures": [
    {
      "id": null,
      "updated_at": null,
      "created_at": null,
      "legacy_id": null,
      "tiles": [
        {
          "id": null,
          "updated_at": null,
          "created_at": null,
          "name": null,
          "length": 86400,
          "multiplier": "1.0",
          "quantity": "1.0",
          "period": "day",
          "price_in_cents": 5000,
          "price_id": null
        },
        {
          "id": null,
          "updated_at": null,
          "created_at": null,
          "name": null,
          "length": 172800,
          "multiplier": "2.0",
          "quantity": "2.0",
          "period": "day",
          "price_in_cents": 10000,
          "price_id": null
        },
        ...
      ]
    }
  ]
}

Allows you to get the pricing structure of the product

HTTP Request

GET /products/:product_id/prices

Orders

Here's an example order

{
    "order": {
        "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
        "updated_at": "2018-01-12T13:04:40.540Z",
        "created_at": "2018-01-12T13:04:38.517Z",
        "legacy_id": null,
        "number": 1,
        "status": "concept",
        "starts_at": null,
        "stops_at": null,
        "price": 0.0,
        "price_with_tax": 0.0,
        "grand_total": 0.0,
        "grand_total_with_tax": 0.0,
        "price_in_cents": 0,
        "price_with_tax_in_cents": 0,
        "customer_id": null,
        "grand_total_in_cents": 0,
        "grand_total_with_tax_in_cents": 0,
        "paid_in_cents": 0,
        "deposit_paid_in_cents": 0,
        "discount_percentage": 0.0,
        "discount_in_cents": 0,
        "discount_with_tax_in_cents": 0,
        "deposit_in_cents": 0,
        "deposit_type": "none",
        "deposit_value": 0.0,
        "tags": [],
        "tax_region_id": null,
        "item_count": 0,
        "entirely_started": true,
        "entirely_stopped": true,
        "item_ids": [],
        "stock_item_ids": [],
        "invoice_count": 0,
        "price_as_decimal": 0,
        "price_with_tax_as_decimal": 0,
        "grand_total_as_decimal": 0,
        "grand_total_with_tax_as_decimal": 0,
        "paid_as_decimal": 0,
        "deposit_paid_as_decimal": 0,
        "discount_as_decimal": 0,
        "discount_with_tax_as_decimal": 0,
        "deposit_as_decimal": 0,
        "plannings": [],
        "notes": [],
        "tax_values": [],
        "lines": [],
        "properties": []
    }
}

This resource contains all the information about an order, such as the period, customer and products booked on it. It has the following attributes:

Field Type Description
id Integer Readonly Unique primary id
number Integer Unique Order number
status String Readonly Status of the order
customer Customer Associated customer. See Customer
customer_id Integer Optional ID of the associated customer
starts_at DateTime Start date and time of the order
stops_at DateTime Stop date and time of the order
price_in_cents Integer Readonly Price in cents without tax
price_with_tax_in_cents Integer Readonly Price in cents with tax
created_at DateTime Readonly When the order was created
updated_at DateTime Readonly When the order was last updated

When retrieving an order it will include more attributes:

Field Type Description
plannings Array Associated planning. See Planning
lines Array Associated order lines. See OrderLine
tax_values Array Associated tax values. See TaxValue
notes Array Associated notes. See Note

List all orders

Example request

curl --request GET \
  --url 'https://example.booqable.com/api/1/orders'

This request returns JSON structured like this

{
    "orders": [
        {
            "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
            "number": 1,
            "status": "concept",
            ...
        },
        {
            "id": "ea024c26-c322-485b-85ad-f67b890e5346",
            "number": 2,
            "status": "started",
            "starts_at": "2018-01-26T13:45:00.000Z",
            "stops_at": "2018-01-30T13:45:00.000Z",
            "customer_id": "63a28c67-259c-4a27-a482-2aac3c5d705d",
            ...
            "customer": {
                "id": "63a28c67-259c-4a27-a482-2aac3c5d705d",
                "name": "Customer Deee",
                ...
            }
        }
    ],
    "meta": {
        "total_count": 2,
        "total_item_count": 1.0,
        "facets": {
            "tag_list": {
                ...
            },
            "status": {
                "_type": "terms",
                "missing": 0,
                "total": 2,
                "other": 0,
                "terms": [
                    {
                        "term": "started",
                        "count": 1
                    },
                    {
                        "term": "concept",
                        "count": 1
                    }
                ]
            }
        }
    }
}

This endpoint retrieves all orders and can paginated

HTTP Request

GET /orders or GET /orders?per=:per&page=:page or GET /orders?q=:query

Query parameters

Parameter Default Description
page 1 Which page to display
per nil If set it limits the number of orders per page
q nil Allows to search orders for a term, for example q=John would return all orders where the term John shows up

Meta

The meta object contains metadata about the complete collection (not affected by pagination)

Parameter Description
total_count Total amount of orders
tag_list List of tags and ammount of orders tagged
status Shows the ammount of orders with the corresponding statuses

Create a new order

Example request

curl --request POST \
--url 'https://example.booqable.com/api/1/orders' \
--header 'content-type: application/json' \
--data '
    {
        "order": {
            "customer_id": 1,
            "starts_at": "01-01-2018 9:00",
            "stops_at": "01-02-2018 9:00"
        }
    }'

This request returns JSON structured like this

{
    "order": {
        "id": "b1bf94ea-8595-4e17-acb3-b9ab425ed0bf",
        "status": "new",
        "starts_at": "2018-01-01T08:00:00.000Z",
        "stops_at": "2018-02-01T08:00:00.000Z",
        ...
    }
}

Creates a new order with the provided details

HTTP Request

POST /orders

Get a single order

Example request

curl --request GET \
  --url 'https://example.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa'

This request returns JSON structured like this

{
    "order": {
        "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
        "number": 1,
        "status": "concept",
        ...
    }
}

This endpoint will retrieve a single order by id or number

HTTP Request

GET /orders/:id or GET /orders/:number

Update order

Updates an existing order.

Parameters

Parameter Type Description
customer_id Integer The id of the customer
starts_at DateTime Start date and time of the order
stops_at DateTime Stop date and time of the order
start_location_id Integer The id of the start location
stop_location_id Integer The id of the stop location
discount_type String The type of discount
discount_percentage Integer The percentage of the discount
discount_in_cents Integer The amount of the discount in cents
coupon_id Integer The id of the coupon
deposit_type String The type of deposit
deposit_value Integer The amount of the deposit in cents
tax_region_id Integer The id of the tax region
override_period_restrictions Boolean Override period restrictions

Request body example

{
    "order": {
        "stops_at":"2018-01-18T10:15:00.000Z"
    }
}

Example request

curl --request PATCH \
--url 'https://example.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa' \
--header 'content-type: application/json' \
--data '{
    "order": {
        "stops_at":"2018-01-18T10:27:18.238Z"
    }
}'

HTTP Request

PUT /orders/:id or PATCH /orders/:id

Book order's items

Request body example

{
    "ids": {
        // Book a bulk product by providing a product ID and quantity
        "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
        // Book a trackable product by providing a producct ID and quantity
        "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": 1,
        // Book a trackable product by providing a product ID and an array of StockItem IDs
        "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": [
            "a098b498-6f9f-4552-9a24-ec4614260e2e"
        ]
    }
}

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/book'

This request returns JSON structured like this

Reserves given items for the duration of the order.

Bulk items can be booked with just a item group id and quantity, but trackable items offer the choice between just providing an item group id and quantity and then providing the specific item ids when starting the items or providing the item group ids as well as the item ids right away to reserve specific inventory items. You can also mix the two methods for the same item.

HTTP Request

POST /orders/:id/book

Save an order as a concept

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa/concept'

This request returns JSON structured like this

{
    "order": {
        "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
        "number": 1,
        "status": "concept",
        ...
    }
}

A newly created order is by default new and unlisted. To make it viewable for everyone you'll need to save it as a concept.

HTTP Request

POST /orders/:id/concept

Reserve an order

Example request

curl --request POST \
  --url 'https://company.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa/reserve'

This request returns JSON structured like this

{
    "order": {
        "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
        "number": 1,
        "status": "reserved",
        ...
    }
}

Items not available error example

{
    "error": {
        "status": "items_not_available",
        "data": {
            "2": {
                "available": 99,
                "need": 199
            }
        }
    }
}

Reserves an order and books all the products in it. This action is only allowed when the order status is either new or concept

If 1 or more products aren't available in the necessary quantity to fulfill the order a items_not_available error will be raised.

HTTP Request

POST /orders/:id/reserve

Start order

Request body example

{
  "ids": {
    // Bulk products just need the product ID and quantity
    // bulk_product_id: quantity
    "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
    // Trackable products need both the product and individual stock item ids
    // trackable_product_id: [ stock_item_id_1, stock_item_id_2 ]
    "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": [
      "1953296d-98ea-4f08-b27e-0b7d6d9379df",
      "a098b498-6f9f-4552-9a24-ec4614260e2e"
    ]
  }
}

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa/start' \
  --header 'content-type: application/json' \
  --data '{
    "ids": {
        "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
        "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": [
            "1953296d-98ea-4f08-b27e-0b7d6d9379df",
            "a098b498-6f9f-4552-9a24-ec4614260e2e"
        ]
    }
}'

This request returns JSON structured like this

{
    "order": {
        "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
        "number": 1,
        "status": "started",
        "starts_at": "2018-01-01T08:00:00.000Z",
        "stops_at": "2018-01-18T10:15:00.000Z",
        "customer_id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
        "item_count": 4,
    ...
    }
}

To start the oder we need to let the API know which products are being started and in what quantities. We can do this by sending the ids parameter. The API expects a product group id and the quantity for bulk products, but for trackable products it expects both a product group id as well as the product ids of each item being started.

HTTP Request

POST /orders/:id/start

Stop order

Request body example

{
  "ids": {
    // Bulk products just need the product ID and quantity
    // bulk_product_id: quantity
    "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
    // Trackable products need both the product and individual stock item ids
    // trackable_product_id: [ stock_item_id_1, stock_item_id_2 ]
    "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": [
      "1953296d-98ea-4f08-b27e-0b7d6d9379df",
      "a098b498-6f9f-4552-9a24-ec4614260e2e"
    ]
  }
}

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa/stop' \
  --header 'content-type: application/json' \
  --data '{
  "ids": {
    "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
    "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": [
      "1953296d-98ea-4f08-b27e-0b7d6d9379df",
      "a098b498-6f9f-4552-9a24-ec4614260e2e"
    ]
  }
}'

This request returns JSON structured like this

{
  "order": {
    "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
    "number": 1,
    "status": "reserved",
    "starts_at": "2018-01-01T08:00:00.000Z",
    "stops_at": "2018-01-18T10:15:00.000Z",
    "customer_id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
    "item_count": 4,
    ...
  }
}

To stop the oder we need to let the API know which products are being stopped and in what quantities. We can do this by sending the ids parameter. The API expects a product group id and the quantity for bulk products, but for trackable products it expects both a product group id as well as the product ids of each item being stopped.

HTTP Request

POST /orders/:id/stop

Cancel order

Example request

curl --request POST \
  --url https://example.booqable.com/api/1/orders/364a726b-419f-4156-ac29-71e2f1c6aefa/cancel \

This request returns JSON structured like this

{
    "order": {
        "id": "364a726b-419f-4156-ac29-71e2f1c6aefa",
        "number": 1,
        "status": "canceled",
        "starts_at": "2018-01-01T08:00:00.000Z",
        "stops_at": "2018-01-18T10:15:00.000Z",
        "customer_id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
        "item_count": 4,
    ...
    }
}

Cancels an order, can only be called on orders with any of these statues: new, concept, reserved. Canceling a reserved order will free all the products that were reserved with it and cancel all plannings.

HTTP Request

POST /orders/:id/cancel

Revert order to a given status

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/revert?status=concept'

This request returns JSON structured like this

{
    "order": {
        "id": "ea024c26-c322-485b-85ad-f67b890e5346",
        "number": 2,
        "status": "concept",
    ...
    }
}

What status an order can be reverted to depends on it's current status:

Current status Available statuses
reserved concept
started concept, reserved
stopped concept, reserved, started

HTTP Request

POST /orders/:id/revert?status=:status

Query parameters

Parameter Description
status Status to revert to

Archive an order

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/archive'

Archives an order

HTTP Request

POST /orders/:id/archive

Duplicate an order

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/duplicate'

This request returns JSON structured like this

{
    "order": {
        "id": "2c0006d9-d93a-40ea-b9c8-ed4a9d06d3f3",
        "number": 3,
        "status": "concept",
    ...
    }
}

Duplicates an existing order to create a new order

HTTP Request

POST /orders/:id/duplicate

Check availability

Example request

curl --request GET \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/available'

This request returns JSON structured like this

{
  // Bulk product group ID and quanity
    "23b6445d-c846-404b-8628-acb9023d8e5c": {
        "available": 5
    },
  // Trackable product group ID, quantities, and the IDs of the individual products
    "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": {
        "available": 10,
        "available_stock_ids": [
            "53dde854-cc61-4a11-8357-181c0142c249",
            "a394aaab-3804-4dcb-9178-774502ebe126",
            "85dc0d2e-2dfb-42b2-be18-0217002cb66f",
            "a680bcfd-c56a-4efa-8107-3331109b1895",
            "1c202cfe-8563-4654-bbb9-b6a28fab5458",
            "8dea39ad-5228-4aae-96bb-5e8c8b186c6f",
            "7bad5f7e-1039-4c62-9359-3a1a3f35b7c1",
            "faf41263-e811-4f4a-8d6d-95c4efb68817",
            "1953296d-98ea-4f08-b27e-0b7d6d9379df",
            "a098b498-6f9f-4552-9a24-ec4614260e2e"
        ]
    }
}

Gets all the available products for the duration of the given order.

HTTP Request

GET /orders/:id/available

Recalculate prices

Example request

curl --request POST \
  --url 'https://company.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/recalculate_prices'

Recalculates the prices for the given order

HTTP Request

POST /orders/:id/recalculate_prices

Planning

Field Type Description
id Integer Readonly Unique primary id
order_id Integer Readonly ID of the associated order
item_id Integer ID of the associated product
quantity Integer Amount booked
price_each_in_cents Integer Price per quantity in cents
reserved Boolean Whether the planning is reserved
started Integer Number of stock started
stopped Integer Number of stock stopped
charge_label String Label of the price charge
charge_length Integer Length of the price charge in seconds
created_at DateTime Readonly When the planning was created
updated_at DateTime Readonly When the planning was last updated

Delete a planning

Example request

curl --request DELETE \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/plannings/b649dcc8-2c93-45bd-88f3-35e1a8be8356'

Deletes a planning from an order.

HTTP Request

DELETE /orders/:order_id/plannings/:id

Order Lines

Field Type Description
id Integer Readonly Unique primary id
title String Readonly ID of the associated order
quantity Integer Amount booked
price_each_in_cents Integer Price per quantity in cents
price_in_cents Boolean Readonly Total price in cents
price_with_tax_in_cents Integer Readonly Total price with tax in cents
display_price_in_cents Integer Readonly Display price in cents, depending if prices are set to including or excluding tax
position String Position of the line on the order
planning_id Integer Readonly ID of the associated planning. May be blank if there is no planning associated
order_id Integer Readonly ID of the associated order
tax_category_id Integer ID of the associated tax category
created_at DateTime Readonly When the planning was created
updated_at DateTime Readonly When the planning was last updated

When retrieving a specific line it will also include the associated order and tax category.

Create a new line

Request body example

{
  "line": {
    "title": "Nikon FE",
    "quantity": 1,
    "price_each_in_cents": 500
  }
}

Example request

curl --request POST \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/lines' \
  --header 'content-type: application/json' \
  --data '{
      "line": {
        "title": "Nikon FE",
        "quantity": 1,
        "price_each_in_cents": 500
      }
    }'

This request returns JSON structured like this

{
  "line": {
    "id": "83a3915a-80af-4c4f-ac77-35b1b2498964",
    "title": "Nikon FE",
    "quantity": 1.0,
    "price_each_in_cents": 500,
    "order_id": "ea024c26-c322-485b-85ad-f67b890e5346",
    ...
    "order": {
      "id": "ea024c26-c322-485b-85ad-f67b890e5346",
      "item_ids": [
        "23b6445d-c846-404b-8628-acb9023d8e5c"
      ],
      ...
      "customer": {
        "id": "63a28c67-259c-4a27-a482-2aac3c5d705d",
        "number": 3,
        "name": "Customer Deee",
        "email": "[email protected]",
        ...
        "orders": [
          {
            "id": "ea024c26-c322-485b-85ad-f67b890e5346",
            "number": 2,
            "status": "concept",
            "customer_id": "63a28c67-259c-4a27-a482-2aac3c5d705d",
            ...
          }
        ]
      },
      "plannings": [
        {
          "id": "12e8c770-9025-4243-8b3b-91de340218db",
          ...
          },
          "stock_item_plannings": []
        }
      ],
      "notes": [],
      "tax_values": [],
      "lines": [
        {
          "id": "83a3915a-80af-4c4f-ac77-35b1b2498964",
          "title": "Nikon FE",
          "quantity": 1.0,
          "order_id": "ea024c26-c322-485b-85ad-f67b890e5346",
          ...
        },
        {
          "id": "80879b22-5355-4902-88b2-b6c0f3e5dca5",
          "title": "Arri Alexa",
          "quantity": 1.0,
          "order_id": "ea024c26-c322-485b-85ad-f67b890e5346",
          ...
        }
      ],
      "properties": []
    }
  }
}

Creates a new line in an order with the provided details.

HTTP Request

POST /orders/:order_id/lines

Update a line

Request body example

{
  "line": {
    "quantity": 2
  }
}

Example request

curl --request PATCH \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/lines/83a3915a-80af-4c4f-ac77-35b1b2498964' \
  --header 'content-type: application/json' \
  --data '{
      "line": {
        "quantity": 2
      }
    }'

HTTP Request

PUT /orders/:order_id/lines/:id or PATCH /orders/:order_id/lines/:id

Update line positions

Example request

curl --request POST \
  --url 'https://company.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/lines/update_positions?ids[]=24fdbdf2-290e-423d-864b-7214a3ae96b3&ids[]=80879b22-5355-4902-88b2-b6c0f3e5dca5

Updates the order of lines in an order.

HTTP Request

POST /orders/:order_id/lines/update_positions?ids[]=:id1&ids[]=:id2...

Query Parameters

Parameter Description
ids[] Line id, each line id needs it's own ids[] and their order determines the update positions

Required in bold

Remove a line

Example request

curl --request DELETE \
  --url 'https://example.booqable.com/api/1/orders/ea024c26-c322-485b-85ad-f67b890e5346/lines/83a3915a-80af-4c4f-ac77-35b1b2498964'

Delete specified line

HTTP Request

DELETE /orders/:order_id/lines/:id

Tags

POST /tags/add?order_id=1&name=delivery

POST /tags/remove?order_id=1&name=delivery

Add a tag

Adds a tag to a resource. A resource could be an order, customer, product group, bundle or document.

Resource parameters

Supply one of the following parameters to add a tag to a resource.

Parameter Description
order_id Id of the order you want to add the tag to.
customer_id Id of the customer you want to add the tag to.
product_group_id Id of the product group you want to add the tag to.
bundle_id Id of the bundle you want to add the tag to.
document_id Id of the document you want to add the tag to.

POST /tags/add?order_id=:order_id&name=:name

Query Parameters

Parameter Description
order_id Id of the order you want to add the tag to (or any other resource id)
name Name of the tag you want to add.

Remove a tag

Removes a tag from an order.

POST /tags/remove?order_id=:order_id&name=:name

Query Parameters

Parameter Description
order_id Id of the order you want to add the tag to (or any other resource id)
name Name of the tag you want to remove.