Pages · Billing

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 /billing returns the card (brand, last four digits, expiry) or payment_method: null.
  • POST /billing/setup with a return_url (https) returns a Stripe-hosted page, valid until expires_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_payment and you receive payment.failed.
  • Saving a new card charges the orders that were waiting after a decline.
  • Cancelling before release refunds any payment (refund.succeeded or refund.failed).

If billing is not available in a mode yet, POST /billing/setup returns 503 billing_unavailable.