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.
When merging an update, keep the retrieved names if you want to retain them, including legacy names that do not meet the current input rules. Responses preserve stored names even when they exceed the current input length limit. An empty or whitespace-only trading_name is normalized to null and clears the field. Changed names are validated rather than silently stripped, transliterated or truncated; preserve the business’s identity when correcting a name.

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. An unchanged stored name is accepted. Changed names must contain at most 2048 characters and use only Unicode letters, combining marks, numbers, spaces, punctuation, + or |, without emoji, control characters or invisible formatting characters. Send null, an empty string or a whitespace-only string to clear and fall back to the legal_name.

Example:

"ACME"

Buyer's full legal name incl. the legal form if applicable. An unchanged stored name is accepted. Changed names must contain at most 2048 characters, include at least one Unicode letter or number and use only letters, combining marks, numbers, spaces, punctuation, + or |, without emoji, control characters or invisible formatting characters.

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 the buyer's invoices. Counts only DUE invoices that Tilta serves, as in the invoice days_past_due field.

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.