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/
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 |
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 |
collection | nil | Filter products groups on a specific collection, use the collection code (slug) as the parameter value |
collection_id | nil | Filter products groups on a specific collection, use the collection id as the parameter value |
tag | nil | Filter product groups on a specific tag, use the tag name as the parameter value |
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. |