Read the Financial Record of a Sale

An order is one financial event. A subscription describes an ongoing commercial relationship; each initial payment, renewal, or billed change inside that relationship becomes a separate order.

Identify why it exists

The billing_reason places an order in its business context:

Value	Source
`purchase`	A one-time checkout
`subscription_create`	The first subscription payment
`subscription_cycle`	A recurring renewal
`subscription_update`	An immediately invoiced prorated subscription change

Every order ties money, discount, tax, customer, product, optional subscription, custom checkout fields, and the resulting invoice together.

Track collection state

State	Interpretation
`pending`	Collection is underway
`paid`	Payment completed, including zero-total orders that require no payment step
`partially_refunded`	Some of the paid amount was returned
`refunded`	The paid amount was fully returned
`void`	Ruba will no longer attempt collection

Charge a saved method without checkout

Off-session charges are a paid-plan preview feature.

Use this flow for a manual service fee, top-up, or other amount that should be charged to an existing customer’s saved payment method. It requires orders:write and organization sales-management permission.

Create a draft

Send POST /v1/orders/ with an existing customer and a one-time fixed-price or free product. The customer must have a complete billing address and at least one saved payment method.

Field	Requirement
`customer_id`	Required; customer must belong to the organization
`product_id`	Required; one-time fixed or free product
`amount`	Optional smallest-currency-unit override, such as `2500` for $25.00
`currency`	Optional lowercase ISO 4217 value; defaults to organization currency
`description`	Optional invoice and receipt line text; defaults to product name
`organization_id`	Required unless the credential is an organization token

curl --request POST \
  --url https://api.getruba.com/v1/orders/ \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "<customer_id>",
    "product_id": "<product_id>",
    "amount": 2500,
    "description": "5,000 extra tokens"
  }'

This creates order.created, but assigns no invoice number and sends no customer email.

Finalize the draft

Send POST /v1/orders/{id}/finalize. Ruba uses the default saved method unless payment_method_id selects another.

curl --request POST \
  --url https://api.getruba.com/v1/orders/<order_id>/finalize \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Success changes the order to paid, assigns the invoice number, grants product benefits, emails confirmation, and emits order.paid. A failed charge returns the order to draft without consuming an invoice number: 402 covers declines, missing methods, or an off-session 3DS/SCA requirement; 403 means the feature or account cannot accept the charge; 412 means the order is no longer a draft.

Invoice and receipt are different

The invoice describes what was sold, including line items, billing identity, tax, and totals. Ruba creates a PDF invoice for every paid order. Generate or retrieve it with the invoice endpoints, or let the customer edit billing identity and download it from the portal. Once generated, merchant-side billing details are frozen; a customer correction regenerates it through the portal. The receipt proves collection. It includes payment method, date, paid amount, applied customer balance, later refunds, and the linked invoice number. Receipt numbers follow RCPT-{customer-id}-{NNNN}. Retrieve one through the merchant endpoint or portal endpoint. The first request may return 202 Accepted while the PDF renders; retry for the presigned URL.

React to state changes

order.created means the record exists, not that it is paid.
order.paid is the fulfillment signal most integrations need.
order.updated reports a later mutation.
order.refunded reports money returned against it.

Full and partial refunds use a separate resource linked to the order. Review refund rules →

Launch Path

Shape the Offer

Run the Revenue Model

Deliver Customer Access

Build the Integration

Operate the Business

Implementation Playbooks

Read the Financial Record of a Sale

Identify why it exists

Track collection state

Charge a saved method without checkout

Invoice and receipt are different

React to state changes

​Identify why it exists

​Track collection state

​Charge a saved method without checkout

​Invoice and receipt are different

​React to state changes

Identify why it exists

Track collection state

Charge a saved method without checkout

Invoice and receipt are different

React to state changes