Menu
Getting started
Cookbooks
API reference
- Overview
- Companies
- Capabilities
- Measures
- Packages
- Unexplained
- Liquidity forecast
- Portfolio
- Customers
- Invoices
- Collections
- Articles
- Set-offs
- Suppliers
- Supplier invoices
- Supplier payment files
- Bank payments
- Expense claims
- Transactions
- Reconciliation
- Bank accounts
- POS sales
- Webshop orders
- Journal entries
- Voucher gap explanations
- Fiscal periods
- Accounts
- Accrual schedules
- Agreements and commitments
- Tax loss carry-forwards
- Fixed assets
- Documents
- Signing requests
- Company registers
- Capital events
- Owner tax
- Inbox items
- Dimensions
- Employees
- Salary runs
- Reports
- Budgets
- Imports
- Compliance check
- Deadlines
- Skatteverket
- Peppol
- Webhooks
- Operations
- Pending operations
- Health
- API key
- Service accounts
Suppliers
AP-side counterparties. Mirrors customers on the supplier vertical.
Endpoints
GET/api/v1/companies/:companyId/suppliers: List suppliers for a company.GET/api/v1/companies/:companyId/suppliers/:id: Retrieve a single supplier by id.POST/api/v1/companies/:companyId/suppliers: Create a supplier.POST/api/v1/companies/:companyId/suppliers/bulk-create: Create up to 50 suppliers in one call (partial-success).PATCH/api/v1/companies/:companyId/suppliers/:id: Partially update a supplier.DELETE/api/v1/companies/:companyId/suppliers/:id: Archive a supplier (soft-delete).
GET /api/v1/companies/:companyId/suppliers
suppliers.list · scope suppliers:read
List suppliers for a company.
Returns active suppliers in created-first order. Pass ?include_archived=true to include archived rows. Use ?search to match against name or org_number.
Use when: You need a supplier roster: for building a UI picker, resolving a supplier_id before registering a supplier invoice, or syncing an external AP system.
Don't use for: Fetching a single supplier you already know the id of: use GET /api/v1/companies/{companyId}/suppliers/{id}. Customers are a separate resource.
Pitfalls
- Archived suppliers are hidden by default; the dashboard makes the same choice.
- org_number identifies legal entities only: suppliers currently have no
individualtype, so the field is Bolagsverket public-record data when present. - vat_number is stored as supplied; unlike customers, suppliers are not auto-validated against VIES on create. Validate externally if the integration requires it.
Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
supplier_type | "swedish_business" | "eu_business" | "non_eu_business" | no | Only suppliers of this type. |
search | string | no | Case-insensitive match on the name (anywhere) or the org number (prefix), 1-200 characters. |
include_archived | "true" | "false" | no | true also returns archived suppliers. Default: false. |
cursor | string | no | Opaque cursor from the previous page's meta.next_cursor. Omit for the first page. |
limit | number | no | Page size, 1-100 (default 50). Larger values are clamped to 100. |
Response fields
| Name | Type | Description |
|---|---|---|
[].id | string | |
[].handle | string (optional) | Typed handle of this supplier: sup_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
[].name | string | |
[].supplier_type | "swedish_business" | "eu_business" | "non_eu_business" | |
[].email | string | null | |
[].org_number | string | null | |
[].vat_number | string | null | |
[].default_payment_terms | number | |
[].default_currency | string | |
[].party_id | string | null (optional) | |
[].archived_at | string | null | |
[].created_at | string |
Example response
{
"data": [
{
"id": "a8f1…",
"name": "Office Depot AB",
"supplier_type": "swedish_business",
"email": "invoices@officedepot.example",
"org_number": "5566778899",
"vat_number": "SE556677889901",
"default_payment_terms": 30,
"default_currency": "SEK",
"archived_at": null,
"created_at": "2026-04-12T08:30:00Z"
}
],
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12",
"next_cursor": null
}
}
GET /api/v1/companies/:companyId/suppliers/:id
suppliers.get · scope suppliers:read
Retrieve a single supplier by id.
Returns the full supplier record. Pass ?expand=supplier_invoices to embed any open supplier invoices (registered / approved / partially_paid / overdue / disputed) for the supplier in the same response. Pass ?expand=party to embed the party (motpart) behind the supplier: legal name, org and VAT number, country, the SCB company-register summary (status, legal form, industry, seat, size, registrations, contact details, fetched date) and what the ledger has seen for it.
Use when: You need the full supplier record: address, payment terms, banking details, default expense account: before booking a supplier invoice or syncing to an external AP system.
Don't use for: Listing suppliers (use the list endpoint). Looking up customer or employee records (different resources).
Pitfalls
- archived_at is non-null when the supplier has been soft-deleted; the supplier is still queryable by id but excluded from default lists.
- Banking fields (bankgiro / plusgiro / iban / bic) are stored as supplied; no Luhn or IBAN check is performed at this layer.
Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
expand | string | no | Comma-separated related records to embed: supplier_invoices, party. An unknown key returns 400 VALIDATION_ERROR. |
Response fields
| Name | Type | Description |
|---|---|---|
id | string | |
handle | string (optional) | Typed handle of this supplier: sup_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
name | string | |
supplier_type | string | |
email | string | null | |
phone | string | null | |
address_line1 | string | null | |
address_line2 | string | null | |
postal_code | string | null | |
city | string | null | |
country | string | |
org_number | string | null | |
vat_number | string | null | |
bankgiro | string | null | |
plusgiro | string | null | |
bank_account | string | null | |
iban | string | null | |
bic | string | null | |
clearing_number | string | null | |
account_number | string | null | |
default_expense_account | string | null | |
default_payment_terms | number | |
default_currency | string | |
self_billing_agreement_ref | string | null | |
auto_debit | boolean | |
default_dimensions | object | |
notes | string | null | |
party_id | string | null | |
archived_at | string | null | |
created_at | string | |
updated_at | string | |
party | object | null (optional) |
Example response
{
"data": {
"id": "a8f1…",
"name": "Office Depot AB",
"supplier_type": "swedish_business",
"email": "invoices@officedepot.example",
"org_number": "556677-8899",
"bankgiro": "123-4567",
"default_expense_account": "5410",
"default_payment_terms": 30,
"default_currency": "SEK",
"archived_at": null,
"created_at": "2026-04-12T08:30:00Z",
"updated_at": "2026-04-30T11:22:09Z"
},
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12"
}
}
POST /api/v1/companies/:companyId/suppliers
suppliers.create · scope suppliers:write
Create a supplier.
Creates a new supplier for the company. Bankgiro (with its Luhn check digit), plusgiro, IBAN and BIC are format-checked, since payment files read them. Omitted supplier_type is swedish_business. Requires Idempotency-Key (UUID). Supports ?dry_run=true: the dry run answers the would-be record without id and timestamps.
Use when: You need to register a new supplier before booking supplier invoices against them. Use dry-run first to catch validation errors before committing.
Don't use for: Updating an existing supplier (PATCH instead). Creating customers (different resource).
Pitfalls
- Idempotency-Key is mandatory: calls without it return 400 VALIDATION_ERROR.
- org_number uniqueness is enforced at the database level; duplicate inserts return 409 SUPPLIER_DUPLICATE_ORG_NUMBER.
- A Swedish-shaped org_number is stored as the 10-digit key; a foreign registration number is stored as sent.
- Unlike customers, suppliers carry no
vat_number_validatedflag: vat_number is stored as supplied without VIES verification. Validate externally if your workflow requires it. - default_expense_account is a BAS account number (e.g. "5410"); the value is stored as-is and used as the suggested debit account when supplier invoices are booked.
- default_dimensions ({"<sie_dim_no>":"<code>"}, codes from GET /dimensions) tags every new supplier invoice of the supplier that sends no default_dimensions of its own; with dimensions enabled an unknown or archived code returns 400 DIMENSION_VALIDATION_FAILED.
Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Request body
| Name | Type | Required |
|---|---|---|
name | string | yes |
supplier_type | "swedish_business" | "eu_business" | "non_eu_business" | no |
email | string | no |
phone | string | no |
address_line1 | string | no |
address_line2 | string | no |
postal_code | string | no |
city | string | no |
country | string | no |
org_number | string | no |
vat_number | string | no |
bankgiro | string | no |
plusgiro | string | no |
bank_account | string | no |
iban | string | no |
bic | string | no |
clearing_number | string | no |
account_number | string | no |
default_expense_account | string | no |
default_payment_terms | number | no |
default_currency | "SEK" | "EUR" | "USD" | "GBP" | "NOK" | "DKK" | "CHF" | "CAD" | null | no |
self_billing_agreement_ref | string | no |
auto_debit | boolean | no |
default_dimensions | object | no |
notes | string | no |
Response fields
| Name | Type | Description |
|---|---|---|
id | string | |
handle | string (optional) | Typed handle of this supplier: sup_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
name | string | |
supplier_type | string | |
email | string | null | |
phone | string | null | |
address_line1 | string | null | |
address_line2 | string | null | |
postal_code | string | null | |
city | string | null | |
country | string | |
org_number | string | null | |
vat_number | string | null | |
bankgiro | string | null | |
plusgiro | string | null | |
bank_account | string | null | |
clearing_number | string | null | |
account_number | string | null | |
iban | string | null | |
bic | string | null | |
default_expense_account | string | null | |
default_payment_terms | number | |
default_currency | string | |
self_billing_agreement_ref | string | null | |
notes | string | null | |
party_id | string | null | |
archived_at | string | null | |
created_at | string | |
updated_at | string | |
auto_debit | boolean | |
default_dimensions | object |
Example request
{
"name": "Office Depot AB",
"supplier_type": "swedish_business",
"email": "invoices@officedepot.example",
"org_number": "556677-8899",
"bankgiro": "123-4567",
"default_expense_account": "5410",
"default_payment_terms": 30,
"default_currency": "SEK"
}
Example response
{
"data": {
"id": "0e9c…",
"name": "Office Depot AB",
"supplier_type": "swedish_business",
"email": "invoices@officedepot.example",
"phone": null,
"address_line1": "Box 123",
"address_line2": null,
"postal_code": "111 22",
"city": "Stockholm",
"country": "SE",
"org_number": "5566778899",
"vat_number": "SE556677889901",
"bankgiro": "123-4567",
"plusgiro": null,
"bank_account": null,
"clearing_number": null,
"account_number": null,
"iban": null,
"bic": null,
"default_expense_account": "5410",
"default_payment_terms": 14,
"default_currency": "SEK",
"default_dimensions": {
"1": "KS01"
},
"notes": null,
"party_id": null,
"archived_at": null,
"created_at": "2026-04-12T08:30:00Z",
"updated_at": "2026-04-12T08:30:00Z"
},
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12"
}
}
POST /api/v1/companies/:companyId/suppliers/bulk-create
suppliers.bulk-create · scope suppliers:write
Create up to 50 suppliers in one call (partial-success).
Bulk-create endpoint mirroring /customers/bulk-create. Each supplier is validated and inserted independently: per-item failures do not roll back items that succeeded. Returns a results array plus a summary. Idempotent over the whole batch. Dry-runnable.
Use when: You're importing a roster of suppliers from another AP system, or seeding a fresh company with its existing vendor list. Use dry-run first to validate the batch.
Don't use for: Updating existing suppliers: PATCH /suppliers/{id} once per supplier. Bulk uploads of > 50 suppliers: split into pages of 50. Transactional all-or-nothing imports: passing all_or_nothing: true returns 501 NOT_IMPLEMENTED.
Pitfalls
- Idempotency-Key is mandatory and covers the WHOLE batch. A retried bulk-create returns the cached full response: it does not retry only the failed items.
- Passing all_or_nothing: true returns 501 NOT_IMPLEMENTED. Today only partial-success batches exist; omit the flag or pass false.
- org_number uniqueness is enforced at the DB level: items with duplicates fail individually with SUPPLIER_DUPLICATE_ORG_NUMBER.
- No VIES validation runs per item; vat_number is stored as supplied. Validate externally if your workflow requires it.
Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Request body
| Name | Type | Required |
|---|---|---|
suppliers | object[] | yes |
all_or_nothing | boolean | no |
Response fields
| Name | Type |
|---|---|
results | object[] |
summary | object |
Example request
{
"suppliers": [
{
"name": "Office Depot AB",
"supplier_type": "swedish_business",
"org_number": "556677-8899"
},
{
"name": "Cloud Hosting GmbH",
"supplier_type": "eu_business",
"vat_number": "DE123456789"
}
]
}
Example response
{
"data": {
"results": [
{
"ok": true,
"request_index": 0,
"data": {
"id": "0e9c…",
"name": "Office Depot AB"
}
},
{
"ok": true,
"request_index": 1,
"data": {
"id": "4d2a…",
"name": "Cloud Hosting GmbH"
}
}
],
"summary": {
"total": 2,
"succeeded": 2,
"failed": 0
}
},
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12"
}
}
PATCH /api/v1/companies/:companyId/suppliers/:id
suppliers.update · scope suppliers:write
Partially update a supplier.
Patches the supplier with the fields sent; every field is optional and the rest stay as they are. An empty string clears a text field (null for email and default_expense_account). archived_at: null un-archives a supplier archived with DELETE. An archived supplier's identifying fields (name, type, org and VAT number, address, bank details) are räkenskapsinformation and cannot change until it is un-archived. The dry run answers the would-be supplier with changes (each changed field, from and to) and payment_details_changed. Idempotent (mandatory Idempotency-Key). Dry-runnable.
Use when: A supplier needs other contact details, address, payment details (bankgiro, plusgiro, clearing and account number, IBAN, BIC), VAT number, default expense account, default dimensions, payment terms or notes, e.g. a supplier imported from SIE with only a name and a bankgiro. Dry-run first to confirm the change.
Don't use for: Archiving a supplier (DELETE sets archived_at). Creating one (POST /suppliers). Merging duplicates: there is no merge; archive the duplicate once its invoices are closed.
Pitfalls
- Idempotency-Key is mandatory; calls without it return 400.
- An empty body returns 400 VALIDATION_ERROR.
- org_number uniqueness is enforced at DB level: 409 SUPPLIER_DUPLICATE_ORG_NUMBER.
- An archived supplier refuses a change to an identifying field with 400 VALIDATION_ERROR (details.field archived_at, details.offending_fields); send archived_at: null first.
- Changing default_expense_account does not rebook earlier supplier invoices: only future bookings pick up the new default.
- default_dimensions replaces the whole bag ({} clears it) and, like the default account, only tags supplier invoices registered after the change; with dimensions enabled an unknown or archived code returns 400 DIMENSION_VALIDATION_FAILED.
- A Swedish bank account payee is clearing_number + account_number; bank_account is free text that payment files only read with an explicit clearing number.
Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
stage | string | no | true stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | |
supplier_type | "swedish_business" | "eu_business" | "non_eu_business" | no | |
email | string | null | no | |
phone | string | no | |
address_line1 | string | no | |
address_line2 | string | no | |
postal_code | string | no | |
city | string | no | |
country | string | no | |
org_number | string | no | |
vat_number | string | no | |
bankgiro | string | no | |
plusgiro | string | no | |
bank_account | string | no | |
iban | string | no | |
bic | string | no | |
clearing_number | string | no | |
account_number | string | no | |
default_expense_account | string | null | no | |
default_payment_terms | number | no | |
default_currency | "SEK" | "EUR" | "USD" | "GBP" | "NOK" | "DKK" | "CHF" | "CAD" | null | no | |
self_billing_agreement_ref | string | null | no | |
auto_debit | boolean | no | |
default_dimensions | object | no | |
notes | string | no | |
archived_at | unknown | no | null un-archives an archived supplier. |
Response fields
| Name | Type | Description |
|---|---|---|
id | string | |
handle | string (optional) | Typed handle of this supplier: sup_ plus its id as 32 lowercase hex. Accepted wherever the id is. |
name | string | |
supplier_type | string | |
email | string | null | |
phone | string | null | |
address_line1 | string | null | |
address_line2 | string | null | |
postal_code | string | null | |
city | string | null | |
country | string | |
org_number | string | null | |
vat_number | string | null | |
bankgiro | string | null | |
plusgiro | string | null | |
bank_account | string | null | |
clearing_number | string | null | |
account_number | string | null | |
iban | string | null | |
bic | string | null | |
default_expense_account | string | null | |
default_payment_terms | number | |
default_currency | string | |
self_billing_agreement_ref | string | null | |
notes | string | null | |
party_id | string | null | |
archived_at | string | null | |
created_at | string | |
updated_at | string | |
auto_debit | boolean | |
default_dimensions | object |
Example request
{
"default_payment_terms": 14,
"notes": "New payment terms agreed 2026-05-12."
}
Example response
{
"data": {
"id": "0e9c…",
"name": "Office Depot AB",
"supplier_type": "swedish_business",
"email": "invoices@officedepot.example",
"phone": null,
"address_line1": "Box 123",
"address_line2": null,
"postal_code": "111 22",
"city": "Stockholm",
"country": "SE",
"org_number": "5566778899",
"vat_number": "SE556677889901",
"bankgiro": "123-4567",
"plusgiro": null,
"bank_account": null,
"clearing_number": null,
"account_number": null,
"iban": null,
"bic": null,
"default_expense_account": "5410",
"default_payment_terms": 14,
"default_currency": "SEK",
"default_dimensions": {
"1": "KS01"
},
"notes": "New payment terms agreed 2026-05-12.",
"party_id": null,
"archived_at": null,
"created_at": "2026-04-12T08:30:00Z",
"updated_at": "2026-05-12T09:00:00Z"
},
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12"
}
}
DELETE /api/v1/companies/:companyId/suppliers/:id
suppliers.delete · scope suppliers:write
Archive a supplier (soft-delete).
Sets archived_at on the supplier; the record is preserved (supplier invoices and audit history remain intact) but excluded from default list responses. To un-archive, PATCH archived_at back to null. Idempotent: archiving an already-archived supplier is a no-op. Dry-runnable.
Use when: You want to remove a supplier from active rosters without losing their history. Idempotent: re-archiving is safe.
Don't use for: Permanently deleting a supplier with all history: the public API does not expose hard-delete. GDPR erasure requests go through a dedicated workflow.
Pitfalls
- Idempotency-Key is mandatory.
- A supplier with any open supplier invoice (registered / approved / partially_paid / overdue / disputed) cannot be archived: returns 409 SUPPLIER_HAS_INVOICES. Close the invoices first. This protects BFL 7 kap audit: the supplier record is the canonical source of seller name/address for invoice reissuance.
- 204 No Content is returned on success: there is no response body to parse.
Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | string | no | true (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits. |
Example response
{
"data": null,
"meta": {
"request_id": "req_…",
"api_version": "2026-05-12"
}
}