NAV Navbar
  • Introduction
  • Endpoint
  • Authentication
  • Customers
  • Product Groups
  • Orders
  • Planning
  • Order Lines
  • 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": "jane@doe.com",
            "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

    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": "jack@doe.com",
            "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": "jane@doe.com",
            "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": "jane@doe.com",
            ...
        }
    }
    

    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

    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?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

    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

    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 an Item Group ID and quantity
            "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
            // Book a trackable product by providing an Item Group ID and quantity
            "cdda5942-19d1-4bc8-ac1b-0324a14ba6d5": 1,
            // Book a trackable product by providing an Item Group ID and an array of Item 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 group ID and quantity
            // bulk_product_group_id: quantity
            "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
            // Trackable products need both the group and individual product ids
            // trackable_product_group_id: [ trackable_product_id_1, trackable_product_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 group ID and quantity
        // bulk_product_group_id: quantity
        "23b6445d-c846-404b-8628-acb9023d8e5cc": 2,
        // Trackable products need both the group and individual product ids
        // trackable_product_group_id: [ trackable_product_id_1, trackable_product_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": "two@world.global",
            ...
            "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