Suppliers

Download schema

List suppliers

GET

https://api.ledgerbee.com/api

/v1/suppliers

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all suppliers for your company, sorted by supplier number. Each supplier carries its full metadata map.

Pass metadata[key]=value query parameters to return only the suppliers whose metadata carries every given key with exactly the given value (AND semantics, exact match, at most 10 pairs). A request with more than 10 pairs returns 400 with error code METADATA_TOO_MANY_FILTERS.

The unfiltered list is cached for 5 seconds; creating a supplier through this API invalidates the cache, so a just-created supplier is immediately visible. A filtered list is never cached, so a metadata change is visible on the next filtered read.

Pagination

The list is returned in full, as an array, unless you send cursor, page or limit. Sending any of them switches the response to a paginated object (data, total, page, limit, totalPages, nextCursor, hasMore); page and limit take their defaults when omitted. A paginated read is never cached.

To walk the whole list, send limit and then pass each response's nextCursor back as cursor, with the same filters, until hasMore is false. Paging by page is deprecated, and page cannot be sent with cursor (400 PAGINATION_CURSOR_WITH_PAGE). A cursor replayed with other filters is refused with 400 PAGINATION_INVALID_CURSOR. From 2026-12-31, a page past the first of a list with more than 10,000 items is refused with 400 PAGINATION_OFFSET_TOO_DEEP.

Required Scope

suppliers-read

List suppliers › query Parameters

object · style: deepObject · explode: true

Exact-match metadata filters in the form metadata[key]=value. Multiple pairs combine with AND semantics — a record matches only if it carries every given key with exactly the given value. At most 10 pairs per request.

cursor

string · maxLength: 4096

Opaque cursor from the previous response's nextCursor. Returns the items after it, in the same order. Send the same filters as the request that produced it, and do not send page. The preferred way to page through the list. Sending cursor, page or limit switches the response from the full array to a paginated object.

page

integer · min: 1 · max: 100000 · deprecated

Deprecated: page with cursor instead. Page number (1-indexed). Sending cursor, page or limit switches the response from the full array to a paginated object. When only limit or cursor is sent, page is 1.

limit

integer · min: 1 · max: 100

Number of items per page. Sending cursor, page or limit switches the response from the full array to a paginated object. When limit is omitted from a paginated request, it is 25.

List suppliers › Responses

The full list of suppliers matching the given filters, or one page of it when cursor, page or limit is sent

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = array
	type = object · requires: data, total, page +4 more

Properties for Variant 1:

SupplierResponse[]

SupplierResponse

id

string · required

The unique identifier of the supplier

Example: 550e8400-e29b-41d4-a716-446655440000

supplierNumber

string · required

Supplier number

Example: V001

name

string · required

Name of the supplier

Example: Acme Supplies

supplierGroupId

string · required

Supplier group ID

Example: 550e8400-e29b-41d4-a716-446655440001

currency

string · required

Currency code

Example: DKK

status

string · enum · required

Supplier status

Enum values:

active

inactive

archived

Example: active

supplierGroupName

string

Supplier group name

Example: Domestic Suppliers

email

string

Email address

Example: contact@acme-supplies.com

phone

string

Phone number

Example: +45 12345678

address

string

Street address

Example: 123 Main Street

city

string

City

Example: Copenhagen

postalCode

string

Postal code

Example: 2100

countryCode

string

Two-letter country code (ISO 3166-1 alpha-2)

Example: DK

vatNumber

string

VAT registration number

Example: DK12345678

attention

string

Attention field

Example: Accounts Payable

paymentTerms

number

Payment terms in days

Example: 30

openingBalance

number

Opening balance in the company base currency (signed: positive = we owe the supplier)

Example: 1000

object

Key-value metadata attached to the supplier

Example: {"erpVendorId":"V-10042","tier":"preferred"}

GET/v1/suppliers

curl https://api.ledgerbee.com/api/v1/suppliers \
  --header 'x-api-key: <api-key>'

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "supplierNumber": "V001",
    "name": "Acme Supplies",
    "supplierGroupId": "550e8400-e29b-41d4-a716-446655440001",
    "supplierGroupName": "Domestic Suppliers",
    "email": "contact@acme-supplies.com",
    "phone": "+45 12345678",
    "address": "123 Main Street",
    "city": "Copenhagen",
    "postalCode": "2100",
    "countryCode": "DK",
    "vatNumber": "DK12345678",
    "currency": "DKK",
    "attention": "Accounts Payable",
    "paymentTerms": 30,
    "openingBalance": 1000,
    "status": "active",
    "metadata": {
      "erpVendorId": "V-10042",
      "tier": "preferred"
    }
  }
]

json

application/json

Create a supplier

POST

https://api.ledgerbee.com/api

/v1/suppliers

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Creates a supplier together with its contacts.

supplierNumber is trimmed and must be unique within your company — a duplicate returns 400 with error code SUPPLIER_NUMBER_ALREADY_EXISTS.

Exactly one contact must be marked as default. When you provide a single contact it is made the default automatically; otherwise a missing or duplicated default returns 400 with error code CONTACT_DEFAULT_REQUIRED or CONTACT_MULTIPLE_DEFAULTS.

supplierGroupId must reference an existing supplier group in your company (404 SUPPLIER_GROUP_NOT_FOUND), and defaultAccountId, when provided, must reference an existing ledger account (404 LEDGER_NOT_FOUND).

An optional metadata map (string keys to string values, at most 50 entries, keys up to 128 characters, values up to 500 characters) is stored with the supplier. An invalid map is rejected before the supplier is created, with error code METADATA_KEY_REQUIRED, METADATA_KEY_TOO_LONG, METADATA_VALUE_TOO_LONG, METADATA_DUPLICATE_KEY or METADATA_TOO_MANY_ENTRIES.

The response contains only the new supplier's id and supplierNumber; fetch the full record, including its metadata, via the list endpoint.

Required Scope

suppliers-write

Create a supplier › Headers

x-api-idempotency-key

string · maxLength: 255

Optional idempotency key for safely retrying mutating requests.

Create a supplier › Request Body

CreateSupplierRequest

supplierNumber

string · required

Unique supplier number

Example: V001

name

string · required

Supplier name

Example: Acme Supplies

supplierGroupId

string · required

Supplier group ID

Example: 550e8400-e29b-41d4-a716-446655440001

currency

string · pattern: ^[A-Za-z]{3}$ · required

The currency this supplier bills us in, ISO 4217 alpha-3.

Example: DKK

countryCode

string · required

Two-letter country code

Example: DK

CreateSupplierContactRequest[] · minItems: 1 · maxItems: 50 · required

Contacts for the supplier. At least one contact with isDefault: true is required.

email

string

Email address

Example: contact@acme-supplies.com

phone

string

Phone number

Example: +45 12345678

address

string · maxLength: 255

Street address

Example: 123 Main Street

city

string

City

Example: Copenhagen

postalCode

string

Postal code

Example: 2100

vatNumber

string

VAT registration number

Example: DK12345678

attention

string

Attention field

Example: Accounts Payable

paymentTerms

number · min: 0

Payment terms in days

Example: 30

openingBalance

number

Opening balance in the company base currency, seeding payables that predate LedgerBee. Signed: positive = we owe the supplier, negative = a credit position.

Example: 1000

defaultAccountId

string

Default ledger account ID

Example: 550e8400-e29b-41d4-a716-446655440002

object

Key-value metadata to attach to the supplier. At most 50 entries; keys up to 128 characters, string values up to 500 characters. Read it back, or filter on it, through the list endpoint.

Example: {"erpVendorId":"V-10042"}

Create a supplier › Responses

Supplier created successfully

CreateSupplierResponse

id

string · required

The unique identifier of the created supplier

Example: 550e8400-e29b-41d4-a716-446655440000

supplierNumber

string · required

Supplier number

Example: V001

POST/v1/suppliers

curl https://api.ledgerbee.com/api/v1/suppliers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "supplierNumber": "V001",
  "name": "Acme Supplies",
  "supplierGroupId": "550e8400-e29b-41d4-a716-446655440001",
  "currency": "DKK",
  "countryCode": "DK",
  "email": "contact@acme-supplies.com",
  "phone": "+45 12345678",
  "address": "123 Main Street",
  "city": "Copenhagen",
  "postalCode": "2100",
  "vatNumber": "DK12345678",
  "attention": "Accounts Payable",
  "paymentTerms": 30,
  "openingBalance": 1000,
  "defaultAccountId": "550e8400-e29b-41d4-a716-446655440002",
  "contacts": [
    {
      "name": "John Doe",
      "email": "john.doe@acme-supplies.com",
      "phone": "+45 12345678",
      "isDefault": true
    }
  ],
  "metadata": {
    "erpVendorId": "V-10042"
  }
}'

Example Request Body

{
  "supplierNumber": "V001",
  "name": "Acme Supplies",
  "supplierGroupId": "550e8400-e29b-41d4-a716-446655440001",
  "currency": "DKK",
  "countryCode": "DK",
  "email": "contact@acme-supplies.com",
  "phone": "+45 12345678",
  "address": "123 Main Street",
  "city": "Copenhagen",
  "postalCode": "2100",
  "vatNumber": "DK12345678",
  "attention": "Accounts Payable",
  "paymentTerms": 30,
  "openingBalance": 1000,
  "defaultAccountId": "550e8400-e29b-41d4-a716-446655440002",
  "contacts": [
    {
      "name": "John Doe",
      "email": "john.doe@acme-supplies.com",
      "phone": "+45 12345678",
      "isDefault": true
    }
  ],
  "metadata": {
    "erpVendorId": "V-10042"
  }
}

json

application/json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "supplierNumber": "V001"
}

json

application/json

Delete a supplier

DELETE

https://api.ledgerbee.com/api

/v1/suppliers/{supplierId}

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Deletes a supplier, together with its contacts, departments and metadata, following the same rules as deleting one in LedgerBee.

A supplier that any booked journal entry or draft entry still points at is not deleted. The request is refused with 400 and the code SUPPLIER_HAS_REFERENCES; details.journalEntryCount and details.draftCount say how many entries point at it. Delete or reassign the drafts first; a supplier with booked entries cannot be deleted.

Returns 404 with the code SUPPLIER_NOT_FOUND when the supplier does not exist in your company.

Required Scope

suppliers-write

Delete a supplier › path Parameters

supplierId

string · required

Supplier ID

Delete a supplier › Headers

x-api-idempotency-key

string · maxLength: 255

Optional idempotency key for safely retrying mutating requests.

Delete a supplier › Responses

Supplier deleted

No data returned

List supplier contacts

GET

https://api.ledgerbee.com/api

/v1/suppliers/{supplierId}/contacts

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all contacts for a supplier, with the default contact first and the rest sorted alphabetically by name.

Returns 404 with error code SUPPLIER_NOT_FOUND when the supplier does not exist in your company.

Required Scope

suppliers-read

List supplier contacts › path Parameters

supplierId

string · required

Supplier ID

List supplier contacts › Responses

List of contacts for a supplier

SupplierContactResponse[]

SupplierContactResponse

id

string · required

The unique identifier of the contact

Example: 550e8400-e29b-41d4-a716-446655440000

name

string · required

Name of the contact

Example: John Doe

isDefaultForSupplier

boolean · required

Whether this is the default contact for the supplier

Example: true

email

string

Email address

Example: john.doe@acme-supplies.com

phone

string

Phone number

Example: +45 12345678

List supplier departments

GET

https://api.ledgerbee.com/api

/v1/suppliers/{supplierId}/departments

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all departments for a supplier, with the default department first and the rest sorted alphabetically by name.

Returns 404 with error code SUPPLIER_NOT_FOUND when the supplier does not exist in your company.

Required Scope

suppliers-read

List supplier departments › path Parameters

supplierId

string · required

Supplier ID

List supplier departments › Responses

List of departments for a supplier

SupplierDepartmentResponse[]

SupplierDepartmentResponse

id

string · required

The unique identifier of the department

Example: 550e8400-e29b-41d4-a716-446655440000

name

string · required

Name of the department

Example: Headquarters

isDefault

boolean · required

Whether this is the default department for the supplier

Example: true

isActive

boolean · required

Whether the department is active

Example: true

poNumber

string

Purchase order number

Example: PO-12345

eanNumber

string

EAN number for e-invoicing

Example: 5790000000000

address

string

Street address

Example: 123 Main Street

city

string

City

Example: Copenhagen

postalCode

string

Postal code

Example: 2100

countryCode

string

Two-letter country code (ISO 3166-1 alpha-2)

Example: DK

List supplier groups

GET

https://api.ledgerbee.com/api

/v1/suppliers/groups

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all supplier groups for your company, sorted alphabetically by name.

The list is cached for 5 seconds.

Required Scope

suppliers-read

List supplier groups › Responses

List of supplier groups for the company

SupplierGroupResponse[]

SupplierGroupResponse

id

string · required

The unique identifier of the supplier group

Example: 550e8400-e29b-41d4-a716-446655440000

name

string · required

Name of the supplier group

Example: Domestic Suppliers

description

string

Description of the supplier group

Example: All domestic supplier accounts

defaultAccountId

string

Default ledger account ID

Example: 550e8400-e29b-41d4-a716-446655440001

Subscriptions VAT Codes