Orders, refunds and disputes - documentation

See every payment taken through your forms, funnels, bookings and bio pages in one place, with refunds, disputes and totals.

Orders is the shared record of every payment taken through Formspring. A payment on a form, a funnel, a booking page or a bio page becomes one order, so you read totals, refunds and disputes in one place instead of four.

Open it from Orders in the dashboard.

What an order holds

The line items, with the quantity and price of each line. The prices are calculated by Formspring when the order is created. A visitor cannot change them from the browser.
The total and currency, plus how much has been refunded and the net amount you keep.
The customer, where the person gave an email address or name.
Where it was taken: the form, funnel, booking page or bio page, and a link to the response or appointment it belongs to.
A timeline of the confirmed payment events behind it.

Statuses

Status	Meaning
Pending	The payment was started and is not confirmed yet.
Paid	The payment was confirmed.
Partially refunded	Part of the amount was given back.
Refunded	The full amount was given back.
Disputed	The customer questioned the payment with their bank and the dispute is still open.
Failed	The payment did not go through. A later retry can still succeed.
Canceled	The checkout was abandoned or expired. A new attempt creates a new order.

An order becomes Paid only when Formspring receives a confirmed payment event from the payment provider. Returning from a checkout page, or anything the browser reports, never marks an order as paid.

Events can arrive twice or out of order. Formspring counts each event once and reaches the same status either way. A late failure notice never turns a paid order back into a failed one.

Refunds

When a payment is refunded, the order shows the refunded amount and the net amount. The original sale is kept: a refund lowers your net revenue, it does not delete the order.

A full refund sets the order to Refunded. A smaller one sets it to Partially refunded.

Disputes

When a customer disputes a payment, the order shows Disputed with the dispute status and the disputed amount. You get an email the first time a dispute appears, and you can start automations on it with the Payment disputed trigger.

While a dispute is open, the amount is on hold.
If you win the dispute, the order goes back to its normal status.
If you lose it, the disputed amount is deducted from the net amount.

Respond to a dispute in your payment provider dashboard before its deadline. Formspring shows the outcome but does not submit evidence for you.

Orders next to responses

The order appears beside the response it belongs to: in a form response, a funnel response and on a booking in Scheduled bookings. You see the items, the total, the status and a link to the full order.

Subscriptions

A funnel that sells a subscription creates one order for the first payment. Every renewal invoice creates its own order, linked to the first one, so each charge and refund is visible on its own.

Webhook events to subscribe to

Refunds, disputes and renewals reach Formspring only if their event is subscribed on the right webhook endpoint in your payment provider dashboard. Subscribe each endpoint to these events:

Payments endpoint (forms, bookings, bio pages and native funnel payments): payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled, charge.succeeded, charge.refunded, charge.dispute.created, charge.dispute.updated, charge.dispute.closed, charge.dispute.funds_withdrawn, charge.dispute.funds_reinstated.

Funnel checkout endpoint (funnel Checkout Sessions and subscriptions): checkout.session.completed, checkout.session.expired, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, payment_intent.succeeded, payment_intent.payment_failed, charge.succeeded, charge.refunded, the five charge.dispute.* events above, invoice.paid, invoice.payment_failed and customer.subscription.deleted.

Without the refund and dispute events, an order stays Paid after the money moved back.

REST API

Orders are read-only over the API and need the orders:read token ability.

bash

curl -s https://formspring.io/api/v1/orders?status=paid \
  -H "Authorization: Bearer $FORMSPRING_TOKEN"

Endpoint	Returns
`GET /api/v1/orders`	A page of orders. Filters: `status`, `source_type`, `subject_type`, `subject_id`, `from`, `to`, `q` (customer email or name), `per_page`.
`GET /api/v1/orders/{order}`	One order with line items, the stable field id each line came from, refund and dispute facts, and the event timeline.
`GET /api/v1/orders/summary`	Gross, refunded, disputed and net totals of paid orders, one row per currency.

Amounts are integers in the smallest currency unit, so 4900 with currency usd is $49.00. An order from another workspace answers 404.

Form responses, funnel responses and the MCP get_submission and get_funnel_submission tools include an orders list for the payments taken with that response.

MCP

AI agents use the same data through three read-only tools: list_orders, get_order and get_orders_summary. They need the orders:read ability and accept the same filters as the REST endpoints.

Automations

Workspace automations can start on Payment confirmed, Payment refunded and Payment disputed. Each fires once per change, even when the provider repeats an event.