> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Read the Financial Record of a Sale
> Understand the transaction record behind purchases, renewals, invoices, and receipts
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
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.
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 |
```bash theme={"system"}
curl --request POST \
--url https://api.getruba.com/v1/orders/ \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"customer_id": "",
"product_id": "",
"amount": 2500,
"description": "5,000 extra tokens"
}'
```
This creates `order.created`, but assigns no invoice number and sends no customer email.
Send `POST /v1/orders/{id}/finalize`. Ruba uses the default saved method unless `payment_method_id` selects another.
```bash theme={"system"}
curl --request POST \
--url https://api.getruba.com/v1/orders//finalize \
--header 'Authorization: Bearer ' \
--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](/api-reference/orders/post-invoice), 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](/api-reference/orders/get-receipt) or [portal endpoint](/api-reference/customer-portal/orders/get-receipt). The first request may return `202 Accepted` while the PDF renders; retry for the presigned URL.
## React to state changes
* [`order.created`](/api-reference/webhooks/order.created) means the record exists, not that it is paid.
* [`order.paid`](/api-reference/webhooks/order.paid) is the fulfillment signal most integrations need.
* [`order.updated`](/api-reference/webhooks/order.updated) reports a later mutation.
* [`order.refunded`](/api-reference/webhooks/order.refunded) reports money returned against it.
Full and partial refunds use a separate resource linked to the order. [Review refund rules →](/features/refunds)