Prepare invoices and confirm issue

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

AI is optional. You confirm invoice and quote issuance in Pepper.

Draft fields

Create and preview require customer_id, currency_code, issue_date, due_date and line_items. Send a permitted active customer ID, or null for an unassigned draft. Use a supported currency and 1 to 100 lines.

Dates use YYYY-MM-DD. The due date cannot precede the issue date.

Optional fields are language, notes, reference and tax_context. Notes allow 5,000 characters; reference allows 100. Language uses a supported code.

tax_context accepts country, region, county, city and postal_code. Each value is text or null, with at most 255 characters. You supply these matching inputs. Pepper does not determine a jurisdiction from an address or postal code.

Update also requires the current integer lock_version and an editable draft. Every draft write sends the full header and line set.

Create an invoice, quote or pro forma draft with drafts_create: pass document_type as invoice (the default), quote or proforma. A credit note starts from its issued invoice with drafts_credit_note. Prepare a quote for a deal with the Sales tools. Use drafts_update to edit any of these drafts. This does not change its document type.

For percent, discount_value uses basis points: 1000 means 10%. For amount, it uses the invoice currency's minor units.

The owner chooses the tax treatment. Tax setup tools change classes and rules after approval. The same settings section lists rate tools. Financial choices do not grant tax setup access.

Money is exact. A price of "10001" means EUR 100.01, USD 100.01, JPY 10,001 or BHD 10.001.

PHP selects the currency scale and calculates totals. Send money as JSON strings. Keep values above JavaScript’s exact integer limit, 9007199254740991, as strings throughout your client. Do not send floats or numeric money values.

Do not submit totals, status, creator, bank details, legal fields or frozen tax snapshots. Set document_type when creating an invoice, quote or pro forma draft; it cannot be changed by a draft update. Unknown draft fields fail validation.

Prepare a tax choice

Both tools need invoices:read, invoices.manage and access to the record. Their calls save nothing and need no idempotency key.

1. Read the options with owner: "document" or owner: "recurring".
2. For an existing editor, include its record_id in both calls.
3. Set the current customer_id and explicit tax_context in the preparation body.
4. Set selection.source, selection.price_mode and any selected rate or class ID.
5. Read the returned data.policy and confirm the intended treatment.
6. Copy data.preparation unchanged into the line's tax_preparation.
7. Send the same customer, context and choice with the preview and write.

For example, a configured-rule preparation body has this form:

{
  "owner": "document",
  "customer_id": "<permitted-customer-ulid>",
  "tax_context": {"country": "GB", "region": null, "county": null, "city": null, "postal_code": null},
  "selection": {"source": "rules", "price_mode": "inclusive", "tax_rate_id": null, "tax_class_id": "<active-class-ulid>"}
}

The matching draft line uses tax_source: "rules", price_mode: "inclusive" and the same tax_class_id. Its tax_rate_id is null. Keep the response's entire preparation object; do not build one from the displayed rate.

A missing rule or a tie between equally ranked rules refuses preparation. Ask the owner to correct the rules or choose a manual rate. See tax rules.

A changed catalog, customer or permission can invalidate a preparation. Read the current options and record, prepare again, review the result and retry. A preparation never decides your tax jurisdiction.

Keep a saved tax choice

Read the draft before editing. Return each retained line_id and the current lock_version. Keep a line's saved choice unless you intend to replace it. Later changes to a rate, class or rule do not recalculate that saved choice.

To replace it, prepare the new choice. Set tax_rate_reselected: true when selecting the same rate again. Copy the returned preparation into the changed line. A change to price basis alone keeps the saved tax inputs on an existing line.

Existing clients that omit the new tax fields keep manual, tax-exclusive prices, or no tax when no rate is supplied. A new catalog line can inherit its item's price basis and class. An item class never enables configured rules on its own. Earlier saved tax snapshots remain tax-exclusive until you change the basis or select again.

For recurring_save_prepare, send the full lines array with each retained line_id. A returned tax_policy: null marks an older line that uses its live rate. Leaving its tax controls out preserves that behavior. Explicit tax controls make the approval preparation review and freeze the current choice.

You can first use financial preparation with owner: "recurring" and the schedule's record_id. Return its tax_preparation with the explicit line controls. An older live line cannot use the saved-choice exception for a basis change.

Example: preview then save

Use a customer ID from the customer endpoint. This example uses no tax rate. Confirm the correct treatment before issuing.

{
  "customer_id": "<permitted-customer-ulid>",
  "currency_code": "USD",
  "issue_date": "2026-10-08",
  "due_date": "2026-11-08",
  "reference": "Northwind October",
  "line_items": [
    {"description": "Website design for October", "quantity": "1.25", "unit_price": "10001"}
  ]
}

1. POST the JSON to /api/v1/documents/preview.
2. Check data.grand_total of "12501", or USD 125.01.
3. POST the JSON to /api/v1/drafts with Idempotency-Key: northwind-october-1.
4. Open the returned data.href.
5. Review the saved draft in Pepper.

For an update, preview with record_id, its current lock_version and each retained line_id. The preview must use the saved draft's customer and currency. Pepper refuses a line from another record or an outdated version.

Then PUT the full JSON with the latest lock_version to /api/v1/drafts/{id}. Remove record_id from the write. Use a new key for that operation. Do not post tax_rate_snapshot or tax_policy from a read response.

MCP uses documents_preview, followed by drafts_create. Add idempotency_key to the draft call's arguments.

Documents: copies, files, messages and reviews

These tools read and prepare documents as the delegated person, through the same actions as the document page. Nothing here issues, sends or records a payment.

documents_pdf, documents_pdf_copy and documents_xml return a download link that opens once, within five minutes; Pepper checks the person's access again when it opens. See Upload and download files. The PDF of an issued document is its frozen original. A note is internal: it is never on the document and never sent to the customer.

Issue after approval

These three tools need invoices:execute and the delegated user's invoices.finalize permission. They handle one document at a time: an invoice, a quote, a pro forma or a credit note.

Execution also rechecks invoices.manage in the issue action. A custom role needs both invoice permissions and access to that document.

For version 0, the preparation body is {"lock_version": 0}. Use the draft's actual version.

1. Read the saved draft and its latest lock_version.
2. Create a JSON body with that lock_version.
3. POST the body to /api/v1/documents/{id}/issue-approvals with a new Idempotency-Key.
4. If data.status is pending, show data.review_url to the delegated person.
5. Retain data.approval_id and data.nonce for execution.
6. Read /api/v1/approvals/{approval_id} for the decision.
7. If its status is approved, execute the request within its window.

For execution, POST {"nonce": "<returned-nonce>"} to /api/v1/approvals/{approval_id}/execute. Send a new Idempotency-Key header.

MCP uses documents_issue_prepare, approvals_get and documents_issue. Their id is the document ID for preparation and approval ID afterward.

To withdraw a request that you no longer need, POST to /api/v1/approvals/{approval_id}/cancel with a new Idempotency-Key. MCP uses approvals_cancel. You can cancel a request that waits or is approved but not yet executed. After that, nobody can approve or execute it. Every connection can read and cancel its own requests, and only its own.

The preparation response has HTTP 202. It includes the customer, dates, exact totals and expiry. It does not issue anything. A matching approval rule can return approved immediately, with the rule in data.automatic.

Only the delegated person can click Approve issue or Reject in the app. Another staff member cannot approve through the review link.

For a pending request, the delegated person gets an Approval inbox item, an in-app alert and one review email. The email has no nonce or token. The person can turn the email, the alert and push notifications off in the inbox settings.

A request waits for the owner's approval window, which is 10 minutes unless the owner changes it. The owner can set 5 to 1440 minutes in Settings > Agents, under Advanced. Use data.expires_at for the exact time. The decision does not restart the window. approved permits execution; executed confirms issuance.

Execution assigns the next number for that document type and freezes the document. It sends no email and records no payment.

The result includes the issued document and number. Treat only that result or the issued record as proof of issuance.

A changed draft, expired request, revoked connection or lost permission can prevent execution. Prepare a new request when the previous one is stale.

An identical retry of executed approval returns its stored result. It must use the same connection, nonce and execute key.

The approval inbox

Agent approvals at /agent-approvals lists the delegated person's requests by state: waiting, approved, done, rejected, cancelled, out of date and expired. The review page and the inbox item link to it.

The person can select several waiting requests and approve or reject them together. Pepper checks each request on its own. A request whose draft changed becomes out of date, and an expired request stays expired. The page says how many requests it could not decide. Approving in the inbox does not issue anything: the agent still executes each approved request with its nonce.

E-invoice readiness refusal

Required e-invoice readiness also applies after you approve issuance. An unready document remains a draft.

HTTP returns 422 with error.code: einvoice_not_ready. MCP returns isError: true and the same error in structuredContent.

error.problems names each input and includes a fix link only when the delegated person can open it. No invoice number is used.

Online payment preparation

These tools use the delegate's current invoice permissions and record scope:

The MCP names are online-payments_get and online-payments_prepare. Preparation accepts source (invoice or booking), source_id, and amount as an exact positive minor-unit string. For example, "2500" means EUR 25.00 on a EUR invoice. The linked invoice must already be issued and have enough balance. A booking must belong to the platform.

Read rows return money with minor, currency and scale. Fees retain an exact minor string, currency and unit: "provider_minor"; do not interpret a formatted display string as arithmetic.

Preparation makes no provider request and collects no money. Agents cannot enter Stripe keys, start checkout or submit card details. With the delegated person's approval of each step, an agent can switch online payments on or off, refund a card payment of an issued credit note, and check or link a provider operation. See Approve sensitive steps. The owner and authorised staff use the online payment workflow.