# Orb

> Usage-based billing platform. Fetch invoices and mark invoices as paid.

Source: https://cotera.co/docs/reference/tools/individual-tools/orb

---

**Authentication Type:** API Key\
**Description:** Usage-based billing platform. Fetch invoices and mark invoices as paid.

***

## Authentication

To authenticate with Orb, you'll need an Orb API key. Create one in the Orb web app, then add it to your Orb connection in Cotera.

You'll need to provide:

* **apiKey** `string`: Your Orb API key, sent as a Bearer token on every request.

> **Security tip:** Do not commit your Orb API key to version control or share it in public channels. Rotate it immediately if it is ever exposed.

**Rate limit:** 3 requests per second on every plan.

***

## Invoices

Fetch Orb invoices and record payments that were collected outside of Orb.

Both tools return the same invoice object, using Orb's own field names:

* **Amounts** are decimal strings in the invoice currency (e.g. `"125.00"`), not integers.
* **Dates** are ISO 8601 strings.
* **Status** is one of `issued`, `paid`, `synced`, `void`, or `draft`.
* Fields that don't apply to an invoice (for example `paid_at` on an unpaid invoice) are returned as `null`.
* Orb's deprecated `discount` field is not returned — use `discounts` instead.

### Get Invoice

Fetch an Orb invoice by ID. Returns the full invoice: status, amounts, customer, subscription, dates, line items, payment attempts, auto-collection state, and metadata.

**Operation Type:** Query (Read)

**Parameters:**

* **invoice\_id** `string` (required): ID of the Orb invoice to fetch
* **include\_zero\_quantity\_line\_items** `boolean` (nullable): Whether to return line items with a quantity of zero. `null` leaves it to Orb, which returns every line item.

**Returns:**

* **id** `string`: Orb invoice ID
* **invoice\_number** `string` (nullable): Automatically generated invoice number
* **status** `string` (nullable): `issued`, `paid`, `synced`, `void`, or `draft`
* **invoice\_source** `string` (nullable): `subscription`, `partial`, or `one_off`
* **currency** `string` (nullable): ISO 4217 currency code, or a custom pricing unit
* **amount\_due** `string` (nullable): Amount due after credits and customer balance (decimal string)
* **subtotal** `string` (nullable): Total before discounts and minimums (decimal string)
* **total** `string` (nullable): Total after discounts and minimums (decimal string)
* **minimum\_amount** `string` (nullable): Invoice-level minimum amount (decimal string)
* **maximum\_amount** `string` (nullable): Invoice-level maximum amount (decimal string)
* **minimum** `object` (nullable): Invoice-level minimum
* **maximum** `object` (nullable): Invoice-level maximum
* **discounts** `array` (nullable): Invoice-level discounts
* **customer** `object` (nullable): The billed customer
  * **id** `string`: Orb customer ID
  * **external\_customer\_id** `string` (nullable): Your own identifier for the customer, if set
* **subscription** `object` (nullable): The subscription this invoice belongs to, if any
  * **id** `string`: Orb subscription ID
* **memo** `string` (nullable): Free-form memo shown on the invoice
* **metadata** `object`: User-specified key/value pairs
* **hosted\_invoice\_url** `string` (nullable): Link to the hosted invoice page
* **invoice\_pdf** `string` (nullable): Link to download the invoice PDF
* **created\_at** `string` (nullable): When the invoice was created (ISO 8601)
* **invoice\_date** `string` (nullable): Scheduled invoice date (ISO 8601)
* **due\_date** `string` (nullable): When payment is due (ISO 8601); `null` for drafts
* **issued\_at** `string` (nullable): When the invoice was issued (ISO 8601)
* **paid\_at** `string` (nullable): When the invoice was paid (ISO 8601)
* **voided\_at** `string` (nullable): When the invoice was voided (ISO 8601)
* **scheduled\_issue\_at** `string` (nullable): When the invoice is scheduled to issue (ISO 8601)
* **eligible\_to\_issue\_at** `string` (nullable): When a threshold invoice becomes eligible to issue (ISO 8601)
* **will\_auto\_issue** `boolean` (nullable): Whether the invoice will be issued automatically
* **issue\_failed\_at** `string` (nullable): When issuing failed (ISO 8601)
* **payment\_started\_at** `string` (nullable): When a payment was initiated (ISO 8601)
* **payment\_failed\_at** `string` (nullable): When payment last failed (ISO 8601)
* **sync\_failed\_at** `string` (nullable): When syncing to the accounting provider failed (ISO 8601)
* **auto\_collection** `object` (nullable): Automatic collection settings and state
  * **enabled** `boolean` (nullable): Whether Orb will automatically charge the saved payment method
  * **num\_attempts** `number` (nullable): Number of automatic payment attempts made
  * **previously\_attempted\_at** `string` (nullable): Most recent automatic payment attempt (ISO 8601)
  * **next\_attempt\_at** `string` (nullable): Next automatic payment attempt (ISO 8601)
* **payment\_attempts** `array of objects`: Payment attempts made against this invoice
  * **id** `string`: Payment attempt ID
  * **amount** `string` (nullable): Amount attempted (decimal string)
  * **created\_at** `string` (nullable): When the attempt was made (ISO 8601)
  * **payment\_provider** `string` (nullable): Payment provider used: `stripe` or `adyen`
  * **payment\_provider\_id** `string` (nullable): The payment's ID in the external provider (e.g. a Stripe payment intent or invoice ID)
  * **receipt\_pdf** `string` (nullable): URL of the payment receipt PDF
  * **succeeded** `boolean` (nullable): Whether the attempt succeeded
* **line\_items** `array of objects`: Line items on the invoice
  * **id** `string`: Line item ID
  * **name** `string` (nullable): Name of the price associated with this line item
  * **quantity** `number` (nullable): Billed quantity
  * **subtotal** `string` (nullable): Line amount before adjustments (decimal string)
  * **adjusted\_subtotal** `string` (nullable): Line amount after adjustments, before overage conversion, credits, and partial invoicing (decimal string)
  * **amount** `string` (nullable): Final line amount after adjustments and credits (decimal string)
  * **credits\_applied** `string` (nullable): Credits applied to this line (decimal string)
  * **partially\_invoiced\_amount** `string` (nullable): Amount already invoiced by threshold invoices (decimal string)
  * **start\_date** `string` (nullable): Start of the billing period for this line (ISO 8601)
  * **end\_date** `string` (nullable): End of the billing period for this line (ISO 8601)
  * **filter** `string` (nullable): Filter applied to the price, if any
  * **grouping** `string` (nullable): Grouping key for grouped prices, if any
  * **price** `object` (nullable): The Orb price this line item is billed against
  * **adjustments** `array` (nullable): Adjustments (discounts, minimums, maximums) applied
  * **sub\_line\_items** `array` (nullable): Breakdown for matrix and tiered prices
  * **tax\_amounts** `array` (nullable): Taxes applied to this line
  * **usage\_customer\_ids** `array of strings` (nullable): Customer IDs whose usage is aggregated into this line
* **billing\_address** `object` (nullable): Billing address on the invoice
* **shipping\_address** `object` (nullable): Shipping address on the invoice
* **customer\_tax\_id** `object` (nullable): Customer's tax ID
* **credit\_notes** `array` (nullable): Credit notes issued against this invoice
* **customer\_balance\_transactions** `array` (nullable): Customer balance transactions applied to this invoice

Nested pricing and adjustment structures (`price`, `adjustments`, `sub_line_items`, `tax_amounts`, `discounts`, `minimum`, `maximum`, addresses, credit notes, and balance transactions) are passed through exactly as Orb returns them. See Orb's [Fetch invoice](https://docs.withorb.com/api-reference/invoice/fetch-invoice) reference for their shape.

**Example Usage:**

```json
{
  "invoice_id": "PNLHvjxZ7EBHnNiP",
  "include_zero_quantity_line_items": false
}
```

### Mark Invoice as Paid

Set an Orb invoice's status to `paid`, recording the date the payment was received and optionally an external payment ID and a note. Use this when payment was collected outside of Orb. Returns the updated invoice.

**Operation Type:** Mutation (Write)

**Parameters:**

* **invoice\_id** `string` (required): ID of the Orb invoice to mark as paid
* **payment\_received\_date** `string` (required): Date the payment was received, as `YYYY-MM-DD` (e.g. `2023-09-22`)
* **external\_id** `string` (nullable): External ID to associate with the payment (e.g. the Stripe invoice or payment ID)
* **notes** `string` (nullable): Note to associate with the payment

**Returns:**

The updated invoice, with the same fields as [Get Invoice](#get-invoice). After a successful call `status` is `paid` and `paid_at` is set.

**Behavior notes:**

* `payment_received_date` must be a real calendar date in `YYYY-MM-DD` format. It is validated before Orb is called, so impossible dates (e.g. `2026-02-30`) and full timestamps (e.g. `2023-09-22T14:00:00Z`) fail immediately with a clear message. If you are starting from a Unix timestamp, such as a Stripe `paid_at`, convert it to a date first.
* `external_id` and `notes` are only sent to Orb when they are set. `null` or blank values are omitted.
* Orb only allows invoices in the `issued` or `synced` status to be marked as paid. For any other status (`draft`, `paid`, `void`), Orb's error is returned as-is.

**Example Usage:**

```json
{
  "invoice_id": "PNLHvjxZ7EBHnNiP",
  "payment_received_date": "2023-09-22",
  "external_id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "notes": "Paid via Stripe invoice in_1MtHbELkdIwHu7ixl4OzzPMv"
}
```

***

## Common Use Cases

**Reconciling Stripe payments into Orb:**

* Trigger a workflow on the [Stripe `invoice.paid` webhook](https://cotera.co/docs/reference/webhooks/stripe.md), read `orb_invoice_id` from the Stripe invoice's `metadata` (written by [Orb's Stripe Invoice Sync](https://docs.withorb.com/integrations-and-exports/stripe)), then call Mark Invoice as Paid with the Stripe invoice ID as `external_id`
* Use [Stripe Get Invoice](https://cotera.co/docs/reference/tools/individual-tools/stripe.md#get-invoice) to re-fetch the Stripe invoice when you need fields that aren't in the webhook payload

**Checking invoice state before acting:**

* Call Get Invoice first and only mark the invoice as paid when `status` is `issued` or `synced`, so already-paid or voided invoices are skipped cleanly

**Billing and collections reporting:**

* Pull an invoice's totals, line items, and payment attempts to answer billing questions or summarize what a customer was charged for
* Use `payment_attempts` and `auto_collection` to explain why an invoice is still unpaid