title: Catalog description: Reference data: categories, payment methods, registers, descriptions, articles, fees.

Catalog¶

Reference data: categories, payment methods, registers, descriptions, articles, fees.

Write tools¶

Mutates customer data

Calls under this heading change the SaldeoSMART account. Confirm intent before invoking from an autonomous agent.

Tool	Summary
`merge_articles`	Create or update the article (product/service) catalog.
`merge_categories`	Create or update document categories for a company.
`merge_descriptions`	Create or update reusable business-event descriptions.
`merge_fees`	Create or update the accounting-firm fee schedule for one month.
`merge_payment_methods`	Create or update payment methods (e.g. "cash", "transfer", "card").
`merge_registers`	Create or update accounting registers (sales/purchase ledgers).

API reference¶

merge_articles ¶

merge_articles(company_program_id: str, articles: list[ArticleInput]) -> MergeResult | ErrorResponse

Create or update the article (product/service) catalog.

Articles are line-item products keyed by code. Optional foreign_codes map a contractor's external code (per-supplier SKU) to your internal code. Saldeo op: article.merge (SS21).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`articles`	`list[ArticleInput]`	One ArticleInput per article. `name` is required. Set `for_documents` to expose in cost-document line items; `for_invoices` to expose in sales-invoice line items.	required

Returns:

Type	Description
`MergeResult \| ErrorResponse`	MergeResult on success, ErrorResponse on failure.

merge_categories ¶

merge_categories(company_program_id: str, categories: list[CategoryInput]) -> MergeResult | ErrorResponse

Create or update document categories for a company.

Categories classify cost documents (e.g. "Office supplies", "Fuel"). Each item is matched on category_program_id (your ERP-side ID); set it to update an existing category, omit it to create a new one. Saldeo op: category.merge (SS09).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`categories`	`list[CategoryInput]`	One CategoryInput per category. `name` is required.	required

Returns:

Type	Description
`MergeResult \| ErrorResponse`	MergeResult — total + per-item successes/errors. On envelope-level
`MergeResult \| ErrorResponse`	failure, ErrorResponse (see docs/ERROR_CODES.md).

merge_descriptions ¶

merge_descriptions(company_program_id: str, descriptions: list[DescriptionInput]) -> MergeResult | ErrorResponse

Create or update reusable business-event descriptions.

Pre-canned descriptions that bookkeepers attach to documents (e.g. "goods purchase", "service fee"). Saldeo op: description.merge (SS14).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`descriptions`	`list[DescriptionInput]`	One DescriptionInput per row. `value` is required.	required

Returns:

Type	Description
`MergeResult \| ErrorResponse`	MergeResult on success, ErrorResponse on failure.

merge_fees ¶

merge_fees(company_program_id: str, year: Year, month: Month, fees: list[FeeInput]) -> MergeResult | ErrorResponse

Create or update the accounting-firm fee schedule for one month.

Used by accounting offices to bill their clients (e.g. monthly retainer, extra-document fees). All fees are nested under one <FOLDER> of (year, month). Saldeo op: fee.merge (SSK04).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company being billed.	required
`year`	`Year`	4-digit year of the billing folder (e.g. 2024).	required
`month`	`Month`	Month of the billing folder, 1–12.	required
`fees`	`list[FeeInput]`	One FeeInput per fee row. `type`, `value`, and `maturity` (ISO YYYY-MM-DD due date) are required; `maturity` is validated client-side.	required

Returns:

Type	Description
`MergeResult \| ErrorResponse`	MergeResult on success, ErrorResponse on failure.

merge_payment_methods ¶

merge_payment_methods(company_program_id: str, payment_methods: list[PaymentMethodInput]) -> MergeResult | ErrorResponse

Create or update payment methods (e.g. "cash", "transfer", "card").

Each item is matched on payment_method_program_id or payment_method_id for update; without either, a new method is created. Saldeo op: payment_method.merge (SS11).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`payment_methods`	`list[PaymentMethodInput]`	One PaymentMethodInput per method. `name` is required.	required

Returns:

Type	Description
`MergeResult \| ErrorResponse`	MergeResult on success, ErrorResponse on failure.

merge_registers ¶

merge_registers(company_program_id: str, registers: list[RegisterInput]) -> MergeResult | ErrorResponse

Create or update accounting registers (sales/purchase ledgers).

A register groups documents that get posted together (e.g. "VAT-S" for sales). Match on register_program_id or register_id to update. Saldeo op: register.merge (SS10).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`registers`	`list[RegisterInput]`	One RegisterInput per register. `name` is required.	required

Returns:

Type	Description
`MergeResult \| ErrorResponse`	MergeResult on success, ErrorResponse on failure.