Skip to main content
PUT
Replace a buyer
This endpoint fully replaces the data stored for a buyer using standard HTTP PUT semantics. Every field that can be set on a buyer must be included in the request body – any field omitted from the payload will be cleared from the stored record. If you only need to update a subset of fields, retrieve the current buyer first with GET /v1/buyers/{external_id}, merge your changes into the retrieved object, and submit the complete merged payload. Objects like business_identifiers and custom_data are replaced entirely, not merged.
This is a full replacement operation. Any fields present in the existing buyer record but absent from your PUT request body will be erased. Always retrieve the current buyer record first and merge your changes before submitting.

Authorizations

Authorization
string
header
required

Your Tilta API key, sent as Bearer <key>.

Path Parameters

external_id
string
required

Unique identifier of a buyer.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$

Body

application/json
trading_name
string | null
required

Buyer's trading name. Send null to clear and fall back to the legal_name.

Example:

"ACME"

Buyer's full legal name incl. the legal form if applicable.

Example:

"ACME GmbH"

Buyer's legal form which depends on the buyer's registered country. Available legal forms cover Tilta's operating countries.

Available options:
LIMITED_COMPANY,
SOLE_TRADER,
PARTNERSHIP,
PUBLIC_COMPANY,
COOPERATIVE,
GOVERNMENT,
OTHER
registered_at
number | null
required

Buyer's registration date (unix time in seconds). Send null to clear.

Example:

1582896122

incorporated_at
number | null
required

Buyer's date of incorporation (unix time in seconds). Send null to clear.

Example:

1582896122

business_identifiers
object[]
required

List of business identifiers. Replaces the existing set entirely. Send [] to clear all identifiers.

business_address
object
required

Buyer's billing address.

custom_data
object | null
required

Free-form metadata for storing integration-specific data alongside this buyer. Replaces the existing object entirely. Send null to clear.

delivery_address
object | null

Buyer's default delivery address. Send null to clear.

Response

The buyer has been successfully updated.

external_id
string
required

Unique identifier of a buyer.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9-_]+$
created_at
number
required

Timestamp indicating when the buyer was created (unix time in seconds).

Example:

1582896122

updated_at
number
required

Timestamp indicating the last time the buyer was updated (unix time in seconds).

Example:

1582896122

max_days_past_due
integer | null
required

Maximum days past due among DUE invoices.

Buyer's full legal name incl. the legal form if applicable.

Example:

"ACME GmbH"

Buyer's legal form which depends on the buyer's registered country. Available legal forms cover Tilta's operating countries.

Available options:
LIMITED_COMPANY,
SOLE_TRADER,
PARTNERSHIP,
PUBLIC_COMPANY,
COOPERATIVE,
GOVERNMENT,
OTHER
business_address
object
required

Buyer's billing address.

trading_name
string | null

Buyer's trading name. If it's not provided, Tilta will use the legal_name.

Example:

"ACME"

registered_at
number | null

Buyer' registration date (unix time in seconds), when they signed up on your platform.

Example:

1582896122

incorporated_at
number | null

Buyer's date of incorporation (unix time in seconds), meaning the date when the business of registered or started.

Example:

1582896122

business_identifiers
object[] | null

A list of business identifiers

delivery_address
object | null

Buyer's default delivery address.

custom_data
object | null

Free-form metadata for storing integration-specific data alongside this buyer. Replaces the existing object entirely on update.

contacts
object[]

Buyer contacts. Returned when expand includes contacts.