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.
- HTTP, MCP and sign-in
- Find tools and read records
- Prepare invoices and confirm issue
- Prepare a financial tax choice
- Approve tax classes and rules
- Project, purchase, item and report tools
- Order, shipping and return tools
- Calendar events, invitations and private feeds
- Automation rules, runs and signed webhooks
- Form, field and widget tools
- Board, card and file tools
- Errors, retries and revocation
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.
Existing reference links
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