Custom API accountancy integration

Breww's Custom API accountancy integration lets you (or a developer you work with) build your own two-way sync between Breww and any accountancy platform we don't already support natively. It exposes a dedicated set of REST API endpoints that make it possible to read invoices, credit notes, supplier invoices, payments and customer/supplier mappings from Breww, push them into your accountancy software, and then tell Breww what's been uploaded so everything stays in sync.

This is a developer-facing integration. If you just want Breww to sync to one of the accountancy packages we already support (Xero, QuickBooks, Sage Accounting, Sage 200, Fortnox, Exact Online, Clear Books, KashFlow, Visma, Twinfield, Sage 50), use one of those instead — they don't need any development work.

When to use this integration

Use the Custom API accountancy integration if:

• You use an accountancy platform that Breww doesn't integrate with directly.

• You want to push data into an internal system (e.g. a data warehouse, a custom ledger) alongside — or instead of — a traditional accountancy package.

• You need more control over exactly when and how documents are uploaded than Breww's built-in integrations provide.

  If any of Breww's standard accountancy integrations fit your needs, they'll be much quicker to set up and require no development work.

What can be synced

The Custom API accountancy integration supports the same document types as Breww's other accountancy integrations. You're responsible for reading them from Breww and pushing them to your accountancy platform.

"Uploaded" means your code reads the document from Breww and sends it to your accountancy platform. "Downloaded" means your code reads documents in your accountancy platform and uses Breww's standard API endpoints to write that data into Breww.

Setting up the integration

1. Add the integration

1. Go to Integrations → Accountancy.

2. Click Set up Custom API accountancy sync integration.

3. Give the integration a name (this is just for your own reference — useful if you end up with more than one custom integration).

4. Choose whether to prioritise customer chart of accounts. This controls whether account codes set on a customer override those set on a product. If you're not sure, leave this unticked.

5. Save the integration.

   Once saved, you'll be taken to the integration's detail page.

2. Configure your chart of accounts

Before you can start syncing, you need to set up the accounts (nominal codes) that Breww will use when it prepares documents for upload.

1. From the integration detail page, click the Accounts & tracking categories button.

2. Add the account codes from your accountancy platform that you'd like Breww to use.

3. Set your default sales account and default stock item account — these are required before the sync API will return any documents.

4. Optionally, set specific accounts per product, customer, customer type or stock item sub-type. See Chart of accounts (nominal codes) for more detail.

   
   

3. Find your authorisation ID

Every API URL includes an auth_id, which is the ID of the integration you just created. You can find this on the integration's detail page — it's also shown in the browser's URL bar when you're viewing the integration.

All sync endpoints follow this pattern:

https://breww.com/api/v1/<endpoint>/<auth_id>/

For example, for an integration with auth_id=123, orders would be listed at https://breww.com/api/v1/accountancy-sync-orders/123/.

4. Create an API token

Your sync code will need an API token to authenticate with Breww. See our API documentation for how to create one and how to authenticate requests. The token must belong to a user in the same brewery as the integration.

5. Map your existing customers and suppliers

If you already have customers or suppliers in your accountancy platform that also exist in Breww, you'll want to "map" them so Breww knows which record in your accountancy platform corresponds to which Breww customer or supplier. Without mapping, your sync code may create duplicate records in your accountancy platform.

You can map customers and suppliers in two ways:

• From the integration detail page — use the Map customers & suppliers button in the header actions. This lets you map records manually through the Breww UI, exactly like the standard accountancy integrations.

• Via the API — use the accountancy-sync-customers and accountancy-sync-suppliers endpoints (described below) to list unmapped records, then post back the external IDs from your accountancy platform.

How the sync workflow runs

Your sync code will typically loop through the following steps on a schedule (e.g. every 4 hours):

1. List customers/suppliers that need mapping. Call accountancy-sync-customers/<auth_id>/?unmapped=true and accountancy-sync-suppliers/<auth_id>/?unmapped=true. For each record, either look it up in your accountancy platform or create a new one there, then post the external ID back to Breww's update-mapping endpoint.
2. List new customer payments to upload. Call accountancy-sync-customer-payments/<auth_id>/. By default you only get payments with uploaded_to_accountancy_provider=0 (not yet uploaded). Upload them to your accountancy platform, then post the external IDs back to the matching update-status endpoint.
3. List new orders, credit notes and supplier invoices. Call the corresponding accountancy-sync-orders, accountancy-sync-credit-notes and accountancy-sync-supplier-invoices endpoints, upload them, and post the external IDs back.
4. List new payment and credit note allocations. Call accountancy-sync-payments and accountancy-sync-credit-note-allocations. These represent how payments and credit notes are allocated against specific orders. Push them to your accountancy platform and update the status back in Breww.

API endpoints

All endpoints are under https://breww.com/api/v1/ and require the <auth_id> of the integration as part of the URL. All update-* endpoints accept either a single object or a list of objects, so you can batch updates.

For the full request/response schemas, see the OpenAPI documentation — this page covers the behaviour and workflow.

List endpoints

Each list endpoint supports an uploaded_to_accountancy_provider query parameter. The default is 0 (not yet uploaded), which is what you usually want. Other values:

Status update endpoints

After you've uploaded a document to your accountancy platform, tell Breww it's been uploaded so it won't appear in future list calls:

Each status update includes the external ID from your accountancy platform (and, for orders, a URL), so Breww can link back to the record on its detail pages in the UI.

Mapping update endpoints

Using multiple custom integrations at once

You can create more than one Custom API accountancy integration on the same brewery — for example, one for your main accountancy package and a second one that pushes a subset of data to a reporting warehouse. Each integration has its own auth_id and its own list of documents to sync, so they won't interfere with each other. A document uploaded through one integration won't appear in the other integration's list endpoints.

Troubleshooting

The list endpoints are returning an empty list

• Check that the document is actually in a state that qualifies for sync (e.g. invoices must be finalised, not drafts).

• If you recently uploaded items, they'll be filtered out by default — try passing ?uploaded_to_accountancy_provider=1 to see them.

• Your invoices might not be assigned to this accountancy integration. Check the invoicing details in Order/invoice settings, and ensure these invoicing details are being used on your invoices.

I'm getting a 400 error about missing default accounts

Before the API will return orders, credit notes or supplier invoices, the integration's chart of accounts must have a default sales account (for orders and credit notes) and a default stock item account (for supplier invoices). Open Accounts & tracking categories on the integration and set these.

I'm getting "This document is assigned to a different accountancy integration"

This happens if you try to update the status of a document that's already been handled by a different accountancy integration on the same brewery. Each document can only be synced through one integration — either undo the upload on the other integration first, or leave that document out of this sync.

Frequently asked questions

Does this replace Breww's standard API?

No — it sits alongside it. The Custom API accountancy integration exposes a specific set of read/write endpoints tailored to building an accountancy sync. If you need to read or update other data (products, stock, etc.), continue to use Breww's main API.

Where are the endpoints to create orders, assign payments or credit note allocations?

These are separate from the accoutancy-sync endpoints, as they're not necessarily associated with an external accountancy platform. Please review the other sections of the API documentation.