Exported resources

The table below provides an overview of the supported resources, the schema, and any notes on their sync behavior:

Resource	Sync Cadence	Notes	Schema
Billable Metric	Daily	Metric	Billable Metric Export.
Coupon	Daily	Coupons	Coupon Export.
Coupon Redemption	Daily	How to use Coupons	Coupon Redemption Export.
Credit Ledger Entry	Daily	Orb syncs all committed (i.e. non-pending) ledger entries.	This mirrors the schema returned by the Fetch credits ledger endpoint.
Credit note	Daily	Credit notes	Credit note export.
Credit note line item	Daily		Credit note line item export.
Customer	Daily	Customer	This mirrors the schema returned by the Fetch customer endpoint.
Customer Balance Transaction	Daily		Customer Balance Transaction Export.
Daily Line Item Revenue	Daily		Daily Line Item Revenue Export.
Invoice	Daily	Orb syncs invoices, except draft invoices which are filtered out.	This mirrors the schema returned by the Fetch invoice endpoint.
Invoice Line Item Billing	Daily		Invoice Line Item Billing Export.
Item	Daily	Item	Item Export.
Plan	Daily	Plan and Price	This mirrors the schema returned by the Fetch plan endpoint.
Subscription	Daily	Subscription	This mirrors the schema returned by the Fetch subscription endpoint.
Subscription version	Daily	This captures the subscription schedule of a subscription, specifically allowing you to understand plan transitions.	A JSON object with the following keys: start_date, ended_at, plan, subscription_id, subscription_start_date, subscription_ended_at

​

Billable Metric

​

Overview

A billable metric defines an aggregation over usage events.

​

Schema

Field Name	Type	Description
id	string	The ID of the coupon.
updated_at	timestamp	The last updated date of the coupon.
metadata	json	User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary.
name	string	The user provided name of this billable metric.
description	string	The user provided description of this billable metric.
item_id	string	The id of the item, see the Item export.
status	string	Available options: active, draft, or archived.

​

Coupon

​

Overview

A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription.

​

Schema

Field Name	Type	Description
id	string	The ID of the coupon.
updated_at	timestamp	The last updated date of the coupon.
redemption_code	string	This string can be used to redeem this coupon for a given subscription.
discount	json	A JSON blob representing either a PercentageDiscount or AmountDiscount
times_redeemed	int	The number of times this coupon has been redeemed.
duration_in_months	nullable int	This allows for a coupon’s discount to apply for a limited time (determined in months); a null value here means “unlimited time”.
max_redemptions	nullable int	The maximum number of redemptions allowed for this coupon before it is exhausted; null here means “unlimited”.
archived_at	nullable timestamp	An archived coupon can no longer be redeemed. Active coupons will have a value of null for archived_at; this field will be non-null for archived coupons.

​

Coupon Redemption

​

Overview

The Coupon Redemption resource represents a coupon that has been redeemed by a customer.

​

Schema

Field Name	Type	Description
id	string	The ID of the coupon redemption.
updated_at	timestamp	The last updated date of the coupon redemption.
start_date	timestamp	The start date of the coupon redemption.
end_date	nullable timestamp	An optional end date of the coupon redemption.
coupon_id	string	The ID of the coupon.
adjustment_id	string	The ID of the adjustment.
subscription_id	string	The ID of the subscription.
customer_id	string	The ID of the customer.
unredeemed_time	nullable timestamp	An optional timestamp of when the coupon was unredeemed, if it was unredeemed.

​

Credit note

​

Overview

The Credit note resource represents a credit note that has been issued to a customer. A credit note is a document that can be used to decrease the amount due or issue a credit for an already issued invoice.

​

Schema

Field Name	Type	Description
id	string	The ID of the credit note.
updated_at	timestamp	The last updated date of the credit note.
created_at	timestamp	The creation time of the resource in Orb.
voided_at	nullable timestamp	The time at which the credit note was voided in Orb, if applicable.
credit_note_number	string	The unique identifier for credit notes.
invoice_id	string	The id of the invoice resource that this credit note is applied to.
memo	nullable string	An optional memo supplied on the credit note.
reason	nullable string	An optional reason for the credit note. Available options: “Duplicate”, “Fraudulent”, “Order change”, “Product unsatisfactory”.
type	string	The type of credit note. Available options: refund, adjustment.
currency	string	The currency of the credit note.
subtotal	string	The total prior to any creditable invoice-level discounts or minimums.
total	string	The total including creditable invoice-level discounts or minimums, and tax.
customer_id	string	The id of the customer resource that this credit note is applied to.
credit_note_pdf	nullable string	A URL to a PDF of the credit note.

​

Credit Note Line Item

​

Overview

The Credit Note Line Item resource represents a line item that is associated with a credit note.

​

Schema

Field Name	Type	Description
id	string	The ID of the credit note line item.
updated_at	timestamp	The last updated date of the credit note line item.
created_at	timestamp	The creation time of the resource in Orb.
voided_at	nullable timestamp	The date and time when the credit note was voided.
credit_note_id	string	The ID of the credit note.
name	string	The name of the corresponding invoice line item.
amount	string	The amount of the line item, excluding any line item minimums and discounts.
quantity	nullable number	An optional quantity credited.
tax_amounts	dict[]	Any tax amounts applied onto the line item.

​

Customer Balance Transaction

​

Overview

The customer balance is an amount in the customer’s currency, which Orb automatically applies to subsequent invoices. This balance can be adjusted manually via Orb’s webapp on the customer details page.

​

Schema

Field Name	Type	Description
created_at	timestamp	The creation time of this transaction.
starting_balance	decimal	The original value of the customer’s balance prior to the transaction, in the customer’s currency.
ending_balance	decimal	The new value of the customer’s balance after the transaction, in the customer’s currency.
amount	decimal	The value of the amount changed in the transaction.
action	string	Available options: applied_to_invoice, manual_adjustment, prorated_refund, revert_prorated_refund, return_from_voiding, credit_note_applied, credit_note_voided, overpayment_refund
type	string	Available options: increment, decrement
description	nullable string	An optional description provided for manual customer balance adjustments.
invoice_id	nullable string	An optional ID if there is an associated invoice.
credit_note_id	nullable string	An optional ID if there is an associated credit note.
customer_id	string	The ID of the customer.

​

Daily Line Item Revenue

​

Overview

The Daily Line Item Revenue resource can be used to track the daily quantity and associated costs for invoice line items. This resource will function similarly to the subscription costs endpoint, but with more fine grained access to information.

This information can be used to power use cases like:

• Daily revenue recognition workflows
• Running pricing exercises

As mentioned, this resource will track daily quantities, but will reflect intra-day plan changes where applicable. This means that rows may span time periods less than a day in cases where a plan changes. Values in the export are periodic values (as opposed to cumulative values) and only relevant to the applicable timeframe.

The Daily Line Item Revenue resource is conceptually an append only resource. Entries in this table can be reverted. For example, when a backdated operation occurs, this may result in old values changing. When entries are reverted, they will have a corresponding timestamp in their reverted_at field but will still exist in the table. This means that historical queries can be constructed to understand what values were returned in the past.

The Daily Line Item Revenue resource relies on upstream processes running to calculate these values. Importantly, this processing relies on the grace period ending before it can run. This means that entries in this resource will be delayed. On average, we expect this delay to be approximately three days.

​

Schema

Field Name	Type	Description
customer_id	string	The ID of the customer.
subscription_id	nullable string	The ID of the subscription. Note that a subscription ID may not always be present due to things like one-off invoices.
pricing_currency	string	The currency of the underlying price.
invoicing_currency	nullable string	The currency used for invoicing if it differs from the price’s currency. Today, this only occurs if you are using virtual pricing units.
item_id	string	The ID of the item
invoice_id	string	The ID of the invoice
invoice_line_item_id	string	The ID of the invoice line item
price_id	string	The ID of the price
billable_metric_id	nullable string	The ID of the billable metric. Note that a billable metric ID may not be present if the associated price is not usage based.
plan_id	nullable string	The ID of the plan. Note that it may not always be present due to things like one-off invoices.
timeframe_start	timestamp	The inclusive timestamp for the start of the relevant period. Note that entries are scoped to day boundaries, but may start or end in the middle of the day if a plan change occurs.
timeframe_end	timestamp	The exclusive timestamp for the end of the relevant period. Note that entries are scoped to day boundaries, but may start or end in the middle of the day if a plan change occurs.
quantity	decimal	The price’s quantity for the relevant timeframe.
subtotal	decimal	The list price before any adjustments have been applied.
adjusted_subtotal	decimal	The list price after adjustments have been applied. Called the “total” in the subscription costs API. This has been renamed to avoid confusion.
amount	decimal	The list price after: adjustments have been applied, prepaid credits have been applied, overage conversions have been applied, and partial invoice amounts have been applied.
credits_applied	decimal	The number of credits used.
conversion_rate	decimal	The conversion rate between the price currency and the invoicing currency. If they are the same, this is 1.
adjustments	JSONB An array of dictionaries with: adjustment ID, adjustment type, amount, and price IDs.	The adjustments made to line items to account for maximums, minimums, and discounts.
sub_line_items	nullable JSONB If this field is null, the number of sub-line items exceeds 100. This is differentiated from cases with no sub-line items, where the column will be empty JSON.	The serialized sub-line items from the invoice. This field can contain up to 100 sub-line items for a given line item. If the number of sub-line items exceeds 100, this field will not contain any sub-line items.
is_partial_invoice	boolean	True if this line item was part of a Threshold invoice
partially_invoiced_amount	nullable decimal	If this is from a threshold invoice, the amount that was partially invoiced.
reverted_at	nullable timestamp	When this entry was reverted. Entries are reverted when backdated operations occur that change the amounts for a given invoice line item on a specified day. Entries are never deleted and are only marked as reverted to allow for historical tracking of values returned on a given day in the past. A row is valid in this table if reverted_at is null.

​

Invoice Line Item Billing

​

Overview

The Invoice Line Item Billing resource can be used to track the individual line item values for invoices that have been issued / billed.

This information can be used to power use cases like:

• Calculating the precise amounts discounted per line item
• Breaking down the amounts billed for a specific price or billable metric

The Invoice Line Item Billing resource is conceptually an append only resource. There are infrequent cases where entries can be voided (usually from a requested manual intervention). If this has occurred, it will be reflected in the voided_at column.

The Invoice Line Item Revenue resource relies on an invoice being issued before rows are written. Importantly, invoice issuing relies on the grace period ending before it can occur. This means that entries in this resource will be delayed.

​

Schema

Field Name	Type	Description
customer_id	string	The ID of the customer.
subscription_id	nullable string	The ID of the subscription. Note that a subscription ID may not always be present due to things like one-off invoices.
pricing_currency	string	The currency of the underlying price.
invoicing_currency	nullable string	The currency used for invoicing if it differs from the price’s currency. Today, this only occurs if you are using virtual pricing units.
item_id	string	The ID of the item
invoice_id	string	The ID of the invoice
invoice_line_item_id	string	The ID of the invoice line item
price_id	string	The ID of the price
billable_metric_id	nullable string	The ID of the billable metric. Note that a billable metric ID may not be present if the associated price is not usage based.
plan_id	nullable string	The ID of the plan. Note that it may not always be present due to things like one-off invoices.
timeframe_start	timestamp	The inclusive timestamp for the start of the relevant period. Note that entries are scoped to day boundaries, but may start or end in the middle of the day if a plan change occurs.
timeframe_end	timestamp	The exclusive timestamp for the end of the relevant period. Note that entries are scoped to day boundaries, but may start or end in the middle of the day if a plan change occurs.
quantity	decimal	The price’s quantity for the relevant timeframe.
subtotal	decimal	The list price before any adjustments have been applied.
adjusted_subtotal	decimal	The list price after adjustments have been applied. Called the “total” in the subscription costs API. This has been renamed to avoid confusion.
amount	decimal	The list price after: adjustments have been applied, prepaid credits have been applied, overage conversions have been applied, and partial invoice amounts have been applied.
credits_applied	decimal	The number of credits used.
conversion_rate	decimal	The conversion rate between the price currency and the invoicing currency. If they are the same, this is 1.
adjustments	JSONB An array of dictionaries with: adjustment ID, adjustment type, amount, and price IDs.	The adjustments made to line items to account for maximums, minimums, and discounts.
sub_line_items	nullable JSONB If this field is null, the number of sub-line items exceeds 100. This is differentiated from cases with no sub-line items, where the column will be empty JSON.	The serialized sub-line items from the invoice. This field can contain up to 100 sub-line items for a given line item. If the number of sub-line items exceeds 100, this field will not contain any sub-line items.
is_partial_invoice	boolean	True if this line item was part of a Threshold invoice
partially_invoiced_amount	nullable decimal	If this is from a threshold invoice, the amount that was partially invoiced.
voided_at	nullable timestamp	When this entry was voided. Entries are very infrequently voided and usually correspond to manual actions that have taken place at the request of the customer.

​

Item

​

Overview

The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes.

​

Schema

Field Name	Type	Description
name	string	The name of the item.