# 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, customer/supplier mappings and **balance sheet journal entries** 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 Breww already integrates with your accountancy software (see [Supported accountancy platforms](https://breww.com/docs/accountancy/#supported-accountancy-platforms)), use that integration instead, as it doesn't need any development work.

> **Note:**
> You'll need someone comfortable with REST APIs to use this integration. Breww's support team can answer questions about how the endpoints behave, but we can't write the sync code for you.

## 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.

| <br />                        | Uploaded | Downloaded |
| ----------------------------- | -------- | ---------- |
| Invoices                      | ✅        | ✅          |
| Voiding invoices              | ✅        | ✅          |
| Customers & contacts          | ✅        | ✅          |
| Invoice payments              | ✅        | ✅          |
| Payments on accounts          | ✅        | ✅          |
| Credit notes                  | ✅        | ✅          |
| Voiding credit notes          | ✅        | ✅          |
| Credit note allocations       | ✅        | ✅          |
| Supplier invoices             | ✅        | ❌          |
| Supplier invoice attachments  | ❌        | ❌          |
| Balance sheet journal entries | ✅        | ❌          |

"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. When your code creates an order, credit note or allocation in Breww, include `custom_accountancy_integration_auth_id` and the platform's `accountancy_provider_id`, and Breww records it as downloaded so it isn't offered for upload again. For a customer payment, also set `uploaded_to_accountancy_provider` to `7` (downloaded), otherwise Breww lists it for upload. Supplier invoices can't be created through the API.

The accountancy sync endpoints only list finalised documents, so they don't report voided orders or credit notes. To pass voids on to your accountancy platform, check Breww's standard `orders` and `credit-notes` endpoints. To void a document in Breww, update its status through the same endpoints.

Balance sheet journal entries are generated by Breww as costs move through your account. See [Balance sheet syncing via the Custom API integration](https://breww.com/docs/custom-api-accountancy-balance-sheet-syncing/) for the dedicated guide on enabling this and the endpoints involved.

## 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, and is 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 disabled.
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** 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)](https://breww.com/docs/nominal-codes-accountancy-accounts/) for more detail.

<br />

> **Warning:**
> The API will refuse to list orders or credit notes until a default sales account is configured, and will refuse to list supplier invoices until a default stock item account is configured. You'll see a clear error message explaining which account is missing if you've forgotten one.

### 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](https://breww.com/docs/api/) 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.

### 6. (Optional) Enable balance sheet syncing

If you want Breww to keep your balance sheet and COGS up-to-date as costs move through Breww, you can enable balance sheet syncing on the integration. This adds a dedicated journal entries endpoint to the workflow below. See [Balance sheet syncing via the Custom API integration](https://breww.com/docs/custom-api-accountancy-balance-sheet-syncing/) for setup steps and endpoint details.

## 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.
5. **(If balance sheet syncing is enabled) Fetch and confirm balance sheet journal entries.** Call `GET accountancy-sync-balance-sheet-journal-entries/<auth_id>/` to fetch a pending batch, upload the entries to your accountancy platform, then `POST` to the same endpoint's `confirm/` action with the `confirmation_id` from the response and `success: true` (or `false` if the upload failed). This step uses a different shape from the other accountancy-sync endpoints. See [Balance sheet syncing via the Custom API integration](https://breww.com/docs/custom-api-accountancy-balance-sheet-syncing/) for the full details.

> **Note:**
> Customer payments should always be uploaded **before** their order allocations, otherwise the allocations will have nothing to attach to in your accountancy platform.

## 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](https://breww.com/docs/api/). 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:

| Value | Meaning                           |
| ----- | --------------------------------- |
| `0`   | Not uploaded, ready to upload     |
| `1`   | Uploaded                          |
| `2`   | Never upload (marked by the user) |
| `3`   | In progress                       |

| Endpoint                                                        | What it returns                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET accountancy-sync-orders/<auth_id>/`                        | Finalised invoices ready to upload                                                                                                                                                                                                                              |
| `GET accountancy-sync-credit-notes/<auth_id>/`                  | Finalised credit notes ready to upload                                                                                                                                                                                                                          |
| `GET accountancy-sync-supplier-invoices/<auth_id>/`             | Finalised supplier invoices ready to upload                                                                                                                                                                                                                     |
| `GET accountancy-sync-customer-payments/<auth_id>/`             | Customer account payments (top-level payments from customers)                                                                                                                                                                                                   |
| `GET accountancy-sync-payments/<auth_id>/`                      | Order payment allocations (how customer payments are applied to orders)                                                                                                                                                                                         |
| `GET accountancy-sync-credit-note-allocations/<auth_id>/`       | Credit note allocations against invoices                                                                                                                                                                                                                        |
| `GET accountancy-sync-customers/<auth_id>/`                     | Customers (use `?unmapped=true` to see only those without an external ID)                                                                                                                                                                                       |
| `GET accountancy-sync-suppliers/<auth_id>/`                     | Suppliers (use `?unmapped=true` to see only those without an external ID)                                                                                                                                                                                       |
| `GET accountancy-sync-balance-sheet-journal-entries/<auth_id>/` | A pending batch of balance sheet journal entries to upload (when balance sheet syncing is enabled). Has its own confirm flow, see [Balance sheet syncing via the Custom API integration](https://breww.com/docs/custom-api-accountancy-balance-sheet-syncing/). |

### 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:

| Endpoint                                                                 | Purpose                                                              |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `POST accountancy-sync-orders/<auth_id>/update-status/`                  | Mark orders as uploaded/not uploaded/never upload                    |
| `POST accountancy-sync-credit-notes/<auth_id>/update-status/`            | Mark credit notes as uploaded/not uploaded/never upload              |
| `POST accountancy-sync-supplier-invoices/<auth_id>/update-status/`       | Mark supplier invoices as uploaded/not uploaded/never upload         |
| `POST accountancy-sync-customer-payments/<auth_id>/update-status/`       | Mark customer payments as uploaded/not uploaded/never upload         |
| `POST accountancy-sync-payments/<auth_id>/update-status/`                | Mark order payment allocations as uploaded/not uploaded/never upload |
| `POST accountancy-sync-credit-note-allocations/<auth_id>/update-status/` | Mark credit note allocations as uploaded/not uploaded/never upload   |

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.

Balance sheet journal entries don't use the `update-status` shape. They use a `confirmation_id`-based confirm flow instead. See [Balance sheet syncing via the Custom API integration](https://breww.com/docs/custom-api-accountancy-balance-sheet-syncing/) for details.

### Mapping update endpoints

| Endpoint                                                    | Purpose                                       |
| ----------------------------------------------------------- | --------------------------------------------- |
| `POST accountancy-sync-customers/<auth_id>/update-mapping/` | Set the external ID for one or more customers |
| `POST accountancy-sync-suppliers/<auth_id>/update-mapping/` | Set the external ID for one or more suppliers |

## 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, so try passing `?uploaded_to_accountancy_provider=1` to see them.

* Your invoices might not be assigned to this accountancy integration. Check your invoicing details in **Settings** -> **Sales, orders & invoices** -> **Invoicing details**, 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** 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](https://breww.com/docs/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.

## More in this guide

- [Balance sheet syncing via the Custom API integration](https://breww.com/docs/custom-api-accountancy-balance-sheet-syncing.md)