Project, purchase, item and report tools

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Customer accounts

Customer-account tools use the current staff delegate's Customer scope. They do not sign in as the customer or reveal verification codes, sessions or checkout credentials.

List filters include customer_id, status, source_website_id and search. Account states are active and disabled.

Possible duplicates return only each Customer's id and label. Use limit, cursor, sort (created_at or name), dir and include_total for paging. Pages contain 25 records by default; limit accepts 1–100. The default order is oldest first. The account's possible_duplicates field includes the first page and its permitted total. A match grants no purchase access. Use the approved relink action to change the linked Customer.

Access changes, Customer relinking, deletion decisions and account exports use exact approval requests. Each is decided separately.

Account access never grants all purchases or invoices on its linked Customer. Relinking affects future checkout identity; earlier purchases and issued originals retain their original details.

Read Manage customer accounts for the customer and staff workflows.

Projects, purchases and items

These tools use the same records and permissions as the app. Preparation saves the stated reversible change; it does not issue or send anything.

Lists accept limit (25, 50 or 100; default 25), cursor, sort, dir, include_total and search (100 characters maximum). A page returns data and next_cursor, and total when you ask for it.

Use view to filter projects (open, closed), purchases (recorded, unpaid, nofile, voided) or items (all, active, inactive). Purchases also accept period.

Project reads need one of customers.view, projects.use or projects.manage. Project creation, milestones and invoice previews need invoices.manage. The tool reference gives the permission of every tool. Recording a scope with its agreement and approving a milestone are on Project and time tools.

Project creation needs title, customer_id and currency_code. A milestone needs the project id, current version, title, scope_id and unit_price.

Milestones can also include tax_rate_id and due_date. Closing or reopening needs the project id, current version and closed boolean.

Invoice preview and preparation need the project id, issue_date, due_date and milestones. Map each milestone ID to its current version.

Only approved, unreserved milestones qualify. Preparing an invoice does not approve the work. Issuing still needs your approval.

Purchase reads need purchases.view or purchases.view_own. Writes also need purchases.manage and access to that purchase.

Purchase creation needs supplier_id, purchase_date, currency_code and lines. Each line needs entry_mode (net or gross) and amount.

Optional line fields are description, tax, tax_rate_id and category_id. Optional purchase fields are reference, notes and engagement_id.

Purchase updates also need id and the current integer version. The saved currency stays fixed. Recording or clearing payment details, voiding a purchase and exporting a tax period need your approval; see Approve sensitive steps.

Item lists need items.view. Item detail and writes need items.manage, because the detail contains fields from the item editor.

Item creation needs name, unit_price, currency_code and unit_type. Unit types are hour, piece, day, kg and custom.

For custom, include custom_unit. Optional fields are sku, description, tax_rate_id, category_id, is_active, price_mode and tax_class_id.

price_mode is exclusive or inclusive; a new item defaults to exclusive. tax_class_id names an existing active class or is null. A new item defaults to no class. These fields offer defaults for new sales lines. A class never turns configured tax rules on. The person selects those rules in the financial editor or tax preparation call.

Item reads return the saved basis and class with the exact price. A read-only item list omits private editor fields. A new rate or class choice must be active. Keeping an item's existing reference does not replace the tax inputs on saved document lines.

Item updates need id, the current version from items_get, name, unit_price and unit_type. The saved currency stays fixed.

Set is_active to the string "0" to archive an item or "1" to restore it. Issued originals stay unchanged.

Send API amounts as exact minor-unit strings: "12345" means EUR 123.45 or USD 123.45. "10001" means BHD 10.001. The unsigned limit is 9223372036854775807, at most 19 digits. Keep amounts above 9007199254740991 as strings; never convert them to JavaScript numbers or floats.

Every write needs an idempotency key. An identical retry returns its original receipt after current permission and record checks.

Receipts, tax periods and item changes

Receipt to purchase: start an upload with purchases_receipt_prepare, then pass its upload_id to purchases_attach_files or purchases_replace_file. A receipt is a PDF, JPEG, PNG or WebP of at most 10 MB. See Upload and download files. An item bulk action runs each item on its own and lists what it refused.

Import and export item prices

Item imports and exports need approval. They use the same fields and row checks as the catalog CSV workflow.

items_import_prepare accepts up to 500 objects in rows. Its unit_price uses an exact dot-decimal string in currency_code, unlike minor-unit prices in items_create. For example, "100.01" means EUR 100.01. Without a currency column, the import uses the company currency.

Optional price_mode accepts exclusive or inclusive. tax_class_ref accepts a stable id:name reference or a unique active class name. Omitted columns keep the exclusive and no-class defaults. An invalid basis, inactive selection or ambiguous class becomes a row error. Pepper saves valid rows and reports refused rows; it never changes an issued original.

items_export returns a single-use CSV download after approval. Its columns end with currency_code, price_mode and tax_class. Price is a dot-decimal string at that row's currency scale. Rate, category and class references use id:name. Keep those strings intact when another program opens the file.

Reports and safe settings

Report tools require reports:read, data.export and current document access. They return exact monetary strings, with integer record counts.

Dates use YYYY-MM-DD. Aging and statements accept page and per_page (1–100; default 50). Tax results group the chosen period by rate.

Reports keep currencies separate. They do not convert currencies, file returns or export CSV files.

Settings reads return only these named fields:

• company.name, company.country, company.currency, company.timezone.
• localization.region, localization.overrides, localization.default_locale, localization.date_format, localization.time_format, localization.number_format, localization.week_start.
• invoicing.default_payment_terms, invoicing.einvoice_readiness.

Credentials, keys, tokens, mail passwords and bank details never appear in settings_read. A settings change runs only after the delegated person approves it; see Approve sensitive steps.

Assistant provider settings

These tools require a connection delegated to the active installation owner, plus settings.manage. A grant cannot make another role the owner.

Read the current generation before preparing a change. Preparation needs generation, enabled and a UUID idempotency_key. Its other inputs are:

Enabling requires a saved provider key. Enter, replace or remove it in Settings > Assistant. Neither tool accepts credential or delete_credential. Changing provider or compatible destination requires a new key in Pepper.

Show the returned review_url to the owner. After approval, execute with its approval id, nonce and a UUID idempotency_key. Changed settings invalidate the prepared generation; prepare again. Assistant setup cannot use batch approval.

Saving withdraws personal Assistant grants and pending confirmations. It preserves started actions and charged usage. No settings read, preparation or save makes a generation request. The built-in Assistant itself does not receive these owner setup tools.

More reports and settings screens

These reads return what the screen shows to the same person. Settings screens need an administrator.

settings_bank_accounts lists the bank accounts that your invoices show, with each IBAN or account number shortened to its country code and last four characters, such as NL •••• 4300. It never changes an account. settings_intelligence tells whether a credential is set, never the credential. backups_list lists backups; downloading or restoring a backup stays with a person in Pepper. installation_update shows the update screen; installing an update stays with a person. installation_health_refresh runs the checks again and repairs nothing.

Installation health

Optional AI access includes the installation.health read tool (installation_health in MCP), also available at GET /api/v1/installation/health. It requires settings:read and a current active owner or administrator.

The response contains checks, checkedAt and version. Each check contains its key, label, state, lastSuccess, message and a fix with label and href. States are working, warning, failing or never_seen. No credential, customer record or filesystem path is returned.

The tool reads the same results as Installation health. It changes no settings and runs no repair. You decide what to change.

Project tasks and tracked time

Use the Project and time tools to plan tasks, log minutes, run a timer, inspect workload and prepare an invoice from unbilled time. Project creation accepts a billing mode; preview and preparation accept time sources beside milestones.