Browse the manual

Agent API reference

Find the Agent API guides for client setup, tools, invoice confirmation and error recovery.

On this page

The reference now has its own documentation category. AI remains optional, and you confirm invoice issuance.

Orders and shipping

Order tools use the same actions as the staff order workflow. Discover their current schemas through Apps and access, HTTP tool discovery or MCP tools/list.

The connection needs the relevant orders:read, orders:prepare or orders:execute grant. The delegate also needs current order and source-record permissions.

Operation MCP name HTTP route
List permitted orders orders_list GET /api/v1/orders
Read an order orders_get GET /api/v1/orders/{id}
Recalculate a draft proposal orders_quote GET /api/v1/orders/{id}/quote
Save a draft orders_save POST /api/v1/orders/drafts
Review a proposed return credit orders_return_quote GET /api/v1/orders/{id}/return-quote?return_id={return}
Read configured shipping methods shipping_methods GET /api/v1/orders/shipping-methods
Query a table or board views_order GET /api/v1/views/order

Draft saving creates no invoice or reservation. Omit order_id to create a draft; supply it with version to update one.

Draft recalculation needs Manage orders. Return-credit review also needs invoice authority and access to the financial source.

Order lists use page sizes of 25, 50 or 100. Keep the filters and sort unchanged when following next_cursor.

Money uses exact minor-unit strings, such as "2800" for €28.00. Quantities use decimal strings with up to 4 decimal places.

Review consequential order changes

Each operation below has its own _prepare tool and execute tool. MCP replaces the dot with an underscore: orders.place_prepare becomes orders_place_prepare.

Operation key Reviewed effect
orders.place Reserve tracked stock and issue the order's invoice
orders.payment Record incoming money the person confirms they received
orders.cancel Cancel an eligible order after safe payment recovery and release remaining holds
orders.shipment_create Allocate selected quantities to a fulfilment
orders.shipment_step Pick, pack, ship, cancel an unshipped allocation or correct physical tracking
orders.return_request Request a return for selected fulfilled quantities
orders.return_step Receive, inspect, restock or issue the reviewed return credit
orders.delivery_grant Create an expiring link for a paid or free digital purchase
orders.delivery_revoke Revoke a digital delivery grant
orders.packing_slip Export a selected fulfilment's packing slip
shipping.save Save owner-configured shipping rates

Prepare returns a review URL and nonce. The delegated person approves or rejects the exact proposal in Pepper. Execute uses that approval's identifier, nonce and request key.

Placement binds the current order version and quoted digest. Shipment steps also need shipment_id and shipment_version; return steps need return_id and return_version.

An inspection supplies quantity and eligible_quantity for each selected return_line_id. Pepper calculates stored totals through its PHP financial actions.

An inspection's eligible quantity controls restocking. Credit uses the inspected returned quantities and original financial values. Refund through the existing refunds.record or online-refund tools.

Shipping configuration remains owner-only. Packing-slip export needs data.export and current order access; its download is single-use and expires after 5 minutes.

Ordinary order reads contain no private file identifiers or customer download URLs. Delivery execution and retained approval reads recheck entitlement, expiry and revocation.

When order access permits, documents_get includes order_source with its identifier, number, link and economic-transaction identity. Otherwise, order_source is null.

Retry the same request key and unchanged proposal after an unknown response. A changed proposal needs a new review. Pending provider outcomes retain reservations.

See sensitive-action approval and errors and retries for the protocol and recovery rules.

Transport and access

Continue to transport and access.

MCP transport

Continue to mcp transport.

Browser sign-in

Continue to browser sign-in.

Endpoints

Continue to endpoints.

Draft fields

Continue to draft fields.

Example: preview then save

Continue to example: preview then save.

Issue after approval

Continue to issue after approval.

Projects, purchases and items

Continue to projects, purchases and items.

Reports and safe settings

Continue to reports and safe settings.

Forms and custom fields

Continue to forms and custom fields.

Widgets

Continue to widgets.

Boards and cards

Continue to boards and cards.

Files

Continue to files.

Idempotency and conflicts

Continue to idempotency and conflicts.

Errors

Continue to errors.

Revocation and retained evidence

Continue to revocation and retained evidence.

Need help with the product?

Contact support