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 reference for their shape.

Example Usage:

{
  "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. 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:

{
  "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, read orb_invoice_id from the Stripe invoice's metadata (written by Orb's Stripe Invoice Sync), then call Mark Invoice as Paid with the Stripe invoice ID as external_id
• Use Stripe 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