Order tools

An order is a single sale: a customer charged for one or more line items (products). Refunds happen at order level.

Tools

create_order

Create and immediately attempt to charge an order.

readOnly	destructive	idempotent	openWorld
false	false	true	false

Required parameters: customer_id, payment_method_id, items (array of { product_id, quantity }). Optional: currency (defaults to usd), description, shipping_address_id/shipping_address, metadata, source, idempotency_key.

The response includes the order in succeeded or failed state, with the underlying transaction details. An order.succeeded or order.failed webhook will follow.

list_orders

List orders with filters (customer, status, date range) and cursor pagination.

readOnly	destructive	idempotent	openWorld
true	false	true	false

get_order

Get a single order, including its transactions and any refunds.

readOnly	destructive	idempotent	openWorld
true	false	true	false

When the order is a subscription charge (initial or recurring), the response also carries subscription_id, subscription_cycle, attempt_count (failed charge attempts), and next_retry_at (the next scheduled charge time, not an accelerated retry — null once the subscription is no longer active). These let an agent reason about a failed recurring charge — pair them with the order.failed webhook to drive a recovery flow, and call retry_order to re-attempt the charge before the next scheduled run.

refund_order

Refund all or part of a paid order.

readOnly	destructive	idempotent	openWorld
false	true	true	false

Required: order_id. Optional: amount (in cents; defaults to the full remaining balance), idempotency_key.

retry_order

Re-attempt a failed charge (or a failed refund) on an existing order using the card on file. There is no body beyond the order — retry never switches the payment method; to charge a different card, create a new order.

readOnly	destructive	idempotent	openWorld
false	true	true	false

Required: order_id, idempotency_key. Only orders in failed (declined charge) or refund_failed (failed refund) state are eligible; any other state returns an error.

Because subscription cycles are themselves orders, retry_order also re-attempts a failed recurring charge and reconciles the cycle on success, so the daily billing cron will not charge the customer again. Correlate a failed cycle to its subscription via the order’s subscription_id / subscription_cycle. The response is the updated order — inspect status (a re-decline leaves it failed with an incremented attempt_count).