Version: 1

Bookkeep API V1

The Bookkeep API is intended to let you build functional applications and integrations, quickly and easily. The Bookkeep API is organized around REST, has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

HTTP: Basic Auth

Use this for every endpoint except Purchase Orders. Purchase Order endpoints take a separate scoped API key — see the other Basic Auth tab.

The Bookkeep API uses API keys to authenticate requests. You can view and manage your API keys in the Bookkeep Developer Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via HTTP Basic Auth. Provide your Publishable key as the basic auth username value and your Secret key as the basic auth password value. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

  curl -L -X GET 'https://api.bookkeep.com/v1/entities' \
  -H 'Authorization: Basic ZGlsaXAuYmFpcmFnaUBib29ra2VlcC5jbzpXLlM4NVZGbkJyeEY2QmI='

Security Scheme Type:	http
HTTP Authorization Scheme:	basic

HTTP: Basic Auth

This tab covers Purchase Order endpoints only (/v1/entities/{entity_id}/purchase_orders*). They use a separate, scoped API key — not the Publishable/Secret key pair documented in the other Basic Auth tab, which every other endpoint uses. Both tabs are labelled the same because both authenticate over HTTP Basic; the credential differs. Merchants create an API key from Shopify admin → Bookkeep app → Settings → Manage API Keys; each key is bound to a single connected shop. Authentication is HTTP Basic: provide the API key as the username; the password is ignored (use any placeholder, commonly x).

The key's shop must also be linked to the {entity_id} in the path — a valid key for a shop that is not linked to that entity returns 403.

An API key carries one or more scopes, granted per key by the merchant:

Scope	Unlocks
purchase_orders:read	GET /v1/entities/{entity_id}/purchase_orders and GET /v1/entities/{entity_id}/purchase_orders/{uuid} — list and get purchase orders in any status, including line items and supplier details
purchase_orders:write	POST /v1/entities/{entity_id}/purchase_orders, PATCH /v1/entities/{entity_id}/purchase_orders/{uuid}, and PATCH /v1/entities/{entity_id}/purchase_orders/{uuid}/cancel — create and update draft purchase orders, and cancel a purchase order in any status the cancel rules allow. Fetching a single purchase order by uuid is covered by purchase_orders:read above, over any status — there is no separate write-scoped GET.
purchase_order_receipts:read	Required in addition to purchase_orders:read to pass include=receipts on the /v1/entities/{entity_id}/purchase_orders endpoints; narrows included receipts to committed status only

Error shape. Purchase Order endpoints always return {"error": "..."} on failure — or {"errors": [...]} when a validation failure carries several messages — rather than the {error: {message, type}} shape used elsewhere in this API. The difference is deliberate and stable: handle both shapes if you consume other resources alongside this one.

  curl -L -X GET 'https://api.bookkeep.com/v1/entities/<entity_id>/purchase_orders' \
  -u '<api-key>:x'

Security Scheme Type:	http
HTTP Authorization Scheme:	basic