Api Reference

Welcome to the branchbob Api Reference page. This document describes how to interact programmatically with the branchbob platform via our JSON-based Api.

In case our Api does not yet cover your use case, please let us know — we appreciate any feedback via partners@branchbob.com .

Table of contents

Authentication

In order to use the branchbob Api, you need an Api key. New Api keys can be requested via partners@branchbob.com .

Once you obtained an Api Key, it must be used to sign each Api request via the Authorization header (HTTP bearer authentication).

Here is an example: 


Authorization: Bearer 9e73fdef32f1af68e64d3abfe8393d2e.c8108d5764102e4c1b9fc863650d3904419c2276c0545ddfc11bcd605b7c94ac

Errors

In the case of an error, the response be structured as follows.

Here is an example: 


{
  "code": "INVALID_RANGE",
  "message": "the requested from date is too far in the past"
}

The Server responses with following http status codes.

Rate Limits

All Api endpoints are rate-limited to a maximum of 2 requests per second. Please ensure that your application respects these limits by using proper throttling.

Pagination

All list endpoints will result in a paginated list with a maximum size of 100 entries per page. In case there exist more records than currently returned or requested via per_page param, the server will response with the X-Branchbob-Next-Page header.

The header X-Branchbob-Next-Page contains the path for the next page in order to receive additional records. It includes the cursor param with encypted data for the upcoming entries. The per_page param may be part of the X-Branchbob-Next-Page header if the the initial reqeust was made with it.

Request example: 
curl api.branchbob.com/api/v1/orders \
  --request GET \
  -H "Authorization: Bearer {token}"
Response example:
HTTP/1.1 200 OK
Location: /api/v1/orders
X-Branchbob-Next-Page: /api/v1/orders?cursor=kds202skpas-s2-/02k02sl22aJ

...

[
	{"id": "..."},
	{"id": "..."},
	...
]
Follow Request example: 
curl api.branchbob.com/api/v1/orders?cursor=kds202skpas-s2-/02k02sl22aJ \
  --request GET \
  -H "Authorization: Bearer {token}"

Stores

GET /api/v1/stores Get all your stores

All stores will be represented as an array of store objects.

Request example: 
curl api.branchbob.com/api/v1/stores \
  --request GET \
  -H "Authorization: Bearer {token}"
Response example:
[{ StoreObject }, { StoreObject }]

Store object


{
  "id": "ce11dcc4-f1c2-4166-85a1-ce61b2fc0c43",
  "title": "Show Store"
  "created_at": "2023-11-13T10:57:29.912Z",
  "updated_at": "2023-11-13T10:57:38.330Z",
  "url": "https://show-store.mybranchbob.com"
}

Orders

GET /api/v1/orders List all your orders

Returns a list of all your orders from all your stores. If you want to receive orders from one of your stores specifically you need to pass the store_id as parameter

Request example: 
curl api.branchbob.com/api/v1/orders \
  --request GET \
  -H "Authorization: Bearer {token}"

If you want to receive orders from one of your stores specifically you need to pass the store_id as parameter 

curl api.branchbob.com/api/v1/orders?store_id=ce11dcc4-f1c2-4166-85a1-ce61b2fc0c43 \
  --request GET \
  -H "Authorization: Bearer {token}"
Response example:

[
  { OrderObject },
  { OrderObject },
  { OrderObject },
  { ... }
]
GET /api/v1/orders/:id Get a specific order by id

Returns an order for the given id. The order must be part of one of your stores.

Request example: 
  curl api.branchbob.com/api/v1/orders/2c62c9ec-12fd-4341-96be-3207df4acb6e \
    --request GET \
    -H "Authorization: Bearer {token}"
Response example:
{ OrderObject }

Orders object


{
  "id": "24b63e10-72cb-4894-80e0-7ce042044443",
  "number": "AGX-006-1041",
  "store_id": "ce11dcc4-f1c2-4166-85a1-ce61b2fc0c43",
  "created_at": "2023-11-13T10:57:39.594Z",
  "updated_at": "2023-11-13T10:57:39.594Z",
  "currency_code": "EUR",
  "processed_at": null,
  "paid_at": null,
  "refunded_at": null,
  "returned_at": null,
  "shipped_at": null,
  "cancelled_at": null,
  "test": null,
  "total_gross": 87.81,
  "total_gross_formatted": "€87.81",
  "invoice_ids": [
    "90e5d082-7e79-4e93-98e6-1418e1e6e7ff"
  ]
}

Customers

GET /api/v1/customers Get all your customers

Returns a list of all your customers from all your stores.

Request example:
curl api.branchbob.com/api/v1/customers \
  --request GET \
  -H "Authorization: Bearer {token}"
Response example:

[
  { CustomerObject },
  { CustomerObject },
  { CustomerObject },
  {...}
]
GET /api/v1/customers/:id Get a customer by id

Returns a customer based on the given id. The customer must be part of the store in order to be avaible.

Request example: 
curl api.branchbob.com/api/v1/customers/658ffc5c-7f76-4900-9dbb-242d985dd6bf \
  --request GET \
  -H "Authorization: Bearer {token}"
Response example:
{ CustomerObject }

Customer object


{
  "id": "2b7e8c19-30d7-4110-8a53-c13b0a3c42f3",
  "title": "Reichert-Olson",
  "store_id": "ce11dcc4-f1c2-4166-85a1-ce61b2fc0c43",
  "first_name": "Larisa",
  "last_name": "O'Conner",
  "email": "larisa@example.com",
  "company": null,
  "guest": true,
  "created_at": "2023-11-13T10:57:38.747Z",
  "updated_at": "2023-11-13T10:57:38.747Z"
}

Invoices

GET /api/v1/invoices/:id Get an invoice by id

Returns an invoice based on the given id. The id can be found on the list of invoice_ids on the order object. The invoice must be part of the store.

Request example:
curl api.branchbob.com/api/v1/invoices/f90ce03f-982e-43d7-898d-fad743b53291 \
  --request GET \
  -H "Authorization: Bearer {token}"
Response example:
{ InvoiceObject }

Invoice object


{
  "id": "90e5d082-7e79-4e93-98e6-1418e1e6e7ff",
  "created_at": "2023-11-13T10:57:39.673Z",
  "updated_at": "2023-11-13T10:57:40.010Z",
  "currency_code": "EUR",
  "first_name": "Lucie",
  "last_name": "Koepp",
  "company": "Reichert-Olson",
  "street": "Hilpert Fords",
  "street_no": "62298",
  "zip": "02536",
  "city": "Gildatown",
  "country_code": "us",
  "number": "2",
  "issuer_company": "Reichert-Olson",
  "issuer_street": "Torphy Port",
  "issuer_street_no": "2576",
  "issuer_first_name": "Marlys",
  "issuer_last_name": "Bahringer",
  "issuer_zip": "81557",
  "issuer_city": "New Lesleyburgh",
  "issuer_country_code": "DE",
  "issuer_vat_number": null,
  "paid_at": null,
  "note": null,
  "issuer_tax_number": null,
  "issuer_business_number": null,
  "issuer_managing_director": null,
  "issuer_phone": "(594) 422-2438",
  "issuer_email": "dummy@branchbob.com",
  "credit_memo": null,
  "sent_at": null,
  "pdf": "https://invoices.branchbob.com/invoice-2-90e5d082-7e79-4e93-98e6-1418e1e6e7ff.pdf"
}