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.

Go to your account settings page {company-name-here}.booqable.com/account/edit
Name your new key
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/

You must replace {company_slug} with the name of your company.

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]",
        "phone": "string?",
        "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
phone	String	Customers phone number
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

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]",
        "phone": "1598580108",
        "properties_attributes": [
            {
                "type": "Property::Address",
        "name": "Main",
        "address1": "Pieter stuyvesantweg 153",
        "address2": "Unit 504",
        "zipcode": "8937AH",
        "city": "Leeuwarden",
        "country": "Netherlands"
            }
        ]
    }
}

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"
            }
        ]
    }
}'

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": {
        "phone": "06 11223344"
    }
}

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": {
        "phone": "06 11223344"
    }
}'

This request returns JSON structured like this

{
    "customer": {
        "id": "297f2584-5f6c-475d-919f-f8791aa6a06a",
        "name": "Jane Doe",
        "phone": "06 11223344",
        ...
    }
}

Update the details of a customer

HTTP Request

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

Sending a PUT request will return the resource with any changes that were made, but sending a PATCH request will always return a 204 NO CONTENT

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

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

It's important to note that the trackable property, while not required, will default to false and can't be changed later

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

Sending a PUT request will return the resource with any changes that were made, but sending a PATCH request will always return a 204 NO CONTENT

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?interval=month&till=01-02-2018&from=01-01-2018

This request returns JSON structured like this

{
    "2017-12-01 00:00:00 +0100": {
        "reserved": 0,
        "concept": 0,
        "date": "2017-12-01T00:00:00.000+01:00",
        "available": 5,
        "total": 5,
        "interval": "month"
    },
    "2018-01-01 00:00:00 +0100": {
        "reserved": 2,
        "concept": 0,
        "date": "2018-01-01T00:00:00.000+01:00",
        "available": 3,
        "total": 5,
        "interval": "month"
    },
    "2018-02-01 00:00:00 +0100": {
        "reserved": 0,
        "concept": 2,
        "date": "2018-02-01T00:00:00.000+01:00",
        "available": 5,
        "total": 5,
        "interval": "month"
    },
    "2018-03-01 00:00:00 +0100": {
        "reserved": 0,
        "concept": 0,
        "date": "2018-03-01T00:00:00.000+01:00",
        "available": 5,
        "total": 5,
        "interval": "month"
    }
}

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

HTTP Request

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

Query parameters

Parameter	Description	Available options
from	Start date
till	End date
interval	Specifies intervals to split up timeframe in	`minute`, `hour`, `day`, `week`, `month`

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

The product_id is not the same as product_group_id

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

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

Orders default to the status new and need to be changed to concept before become available in the app

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

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

Sending a PUT request will return the resource with any changes that were made, but sending a PATCH request will always return a 204 NO CONTENT

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

Sending a PUT request will return the resource with any changes that were made, but sending a PATCH request will always return a 204 NO CONTENT

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

Introduction

Creating an API key

Contributing

Endpoint

Authentication

Customers

List all customers

HTTP Request

Query parameters

Meta

Create a new customer

HTTP Request

Required parameters

Get a single customer

HTTP Request

Update customer

HTTP Request

Archive customer

HTTP Request

Restore customer

HTTP Request

Product Groups

List all product groups

HTTP Request

Query parameters

Meta

Create a new product group

HTTP Request

Get a single product group

HTTP Request

Update product group

HTTP Request

Archive product group

HTTP Request

Restore product group

HTTP Request

Check availability

HTTP Request

Query parameters

Show product pricing structures

HTTP Request

Orders

List all orders

HTTP Request

Query parameters

Meta

Create a new order

HTTP Request

Get a single order

HTTP Request

Update order

HTTP Request

Book order's items

HTTP Request

Save an order as a concept

HTTP Request

Reserve an order

HTTP Request

Start order

HTTP Request

Stop order

HTTP Request

Cancel order

HTTP Request

Revert order to a given status

HTTP Request

Query parameters

Archive an order

HTTP Request

Duplicate an order

HTTP Request

Check availability

HTTP Request

Recalculate prices

HTTP Request

Planning

Delete a planning

HTTP Request

Order Lines

Create a new line