Billing
A card on file per mode, charged once per order.
Each mode has its own card on file. Orders need one first: without it, POST /orders returns 409 payment_method_required.
GET /billingreturns the card (brand, last four digits, expiry) orpayment_method: null.POST /billing/setupwith areturn_url(https) returns a Stripe-hosted page, valid untilexpires_at, where someone on your team saves a card. Card details go to Stripe only. Test mode takes Stripe's test cards. You can also save a card in the partner portal's Billing tab.
When an order is charged
Each order is charged once, off-session, for its committed total (product plus quoted shipping) when validation passes and the order reaches awaiting_payment. The order's payment object and payment.* events follow the charge.
Payment states: pending, requires_action, succeeded, failed, canceled, unknown.
- A declined card is not charged again until you save a new one. The order waits in
awaiting_paymentand you receivepayment.failed. - Saving a new card charges the orders that were waiting after a decline.
- Cancelling before release refunds any payment (
refund.succeededorrefund.failed).
If billing is not available in a mode yet, POST /billing/setup returns 503 billing_unavailable.