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

Resource Type	Sync Cadence	Notes
Adjustment	Daily	Adjustments
Adjustment Interval	Daily	Adjustments
Billable Metric	Daily	Metric
Coupon	Daily	Coupons
Coupon Redemption	Daily	How to use Coupons
Credit Ledger Entry	Daily	Orb syncs all committed (i.e. non-pending) ledger entries.
Credit note	Daily	Credit notes
Credit note line item	Daily
Customer	Daily	Customer
Customer Balance Transaction	Daily
Daily Line Item Revenue	Daily
Invoice	Daily	Orb syncs invoices, except draft invoices which are filtered out.
Invoice Line Item Billing	Daily
Invoice Metadata	Daily
Item	Daily	Item
Plan	Daily	Plan and Price
Price	Daily	Plan and Price
Price Interval	Daily	Plan and Price
Subscription	Daily	Subscription. The responses mirrors the shape of the fetch subscription endpoint.
Subscription version	Daily	This captures the subscription schedule of a subscription, specifically allowing you to understand plan transitions.

​

General guidance

​

Deletion markers

Orb exports deletion markers to indicate that a resource has been deleted. In general, the majority of Orb’s resources will have a marker, deleted_at, which will be set to the time of deletion, or null if the resource has not been deleted. Certain resources, are append-only and will never be deleted, these do not have a deleted_at field present.

The following resources do not have a deletion marker:

• Credit Ledger Entry
• Daily Line Item Revenue
• Invoice
• Invoice Line Item Billing

​

API based resources

A subset of Orb’s exported resources are based off of the API response shape. These are not directly defined below, but linked to the relevant API reference documentation, and may change as the API evolves.

The following resource schemas are dependent on the API resources:

• Invoice
• Subscription
• Customer

Note that the Subscription and Customer resource will always have deletion markers in addition to the API response shape.

​

Resource schemas

​

Adjustment

​

Overview

The adjustment resource represents a minimum, maximum, or discount that can be applied to a single price or a set of prices. See the Adjustments section for more information. The adjustment table is most useful when joining with other tables using the adjustment_id field. For example,

• you can see how a coupon is defined by the adjustment_id linked on the coupon resource
• you can better understand how an adjustment is applied onto a daily line item revenue resource by inspecting the adjustment_ids column in the Daily Line Item Revenue resource

​

Schema

Field Name	Type	Description
id	string	The ID of the resource.
applies_to_price_ids	string[]	The IDs of the prices that the adjustment applies to.
adjustment_type	string	The type of adjustment. Can be “minimum”, “maximum”, “percentage_discount”, “amount_discount”, or “usage_discount”.
adjustment_value	decimal	The value of the adjustment. For percentage discounts, this is a percentage. For amount discounts, maximums, and minimums, this is an amount in the price’s currency. For usage discounts, this is a percentage.
currency	string	The currency of the adjustment. This is determined by the price’s currency.
reason	nullable string	The reason for the adjustment.
item_id	nullable string	The ID of the item, as it appears on an invoice. This is only applicable for minimums.
is_invoice_level	boolean	Whether the adjustment is an invoice level adjustment or price-level adjustment.
plan_id	nullable string	The ID of the plan, if the adjustment is associated with a plan.
plan_phase_order	nullable int	The order of the plan phase, if the adjustment is associated with a plan and phase.
min_plan_version	nullable int	The minimum plan version, if the adjustment is associated with a plan and version.
max_plan_version	nullable int	The maximum plan version, if the adjustment is associated with a plan and version.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Adjustment Interval

​

Overview

The adjustment interval resource represents a time frame during which an adjustment applies to a subscription. See modifying subscriptions and add or edit price intervals for more information.

​

Schema

Field Name	Type	Description
id	string	The ID of the resource.
subscription_id	string	The ID of the subscription.
customer_id	string	The ID of the customer.
adjustment_id	string	The ID of the adjustment.
start_date_inclusive	timestamp	The start date of the adjustment interval.
end_date_exclusive	nullable timestamp	The end date of the adjustment interval, if defined.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Billable Metric

​

Overview

A billable metric defines an aggregation over usage events.

​

Schema

Field Name	Type	Description
id	string	The ID of the resource.
updated_at	timestamp	The last updated date of the resource.
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.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

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.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Coupon Redemption

​

Overview

The Coupon Redemption resource type 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.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Credit ledger entry

​

Overview

The Credit ledger entry resource represents the various operations that occur for each credit block (e.g. increments and decrements). This resource is helpful to understand how a credit block gets burned down.

​

Schema

Field Name	Type	Description
id	string	The ID of the credit ledger entry.
created_at	timestamp	The creation time of the resource in Orb.
reverted_at	nullable timestamp	If set, the time at which this entry was reverted.
amount	string	The amount that was applied on this credit ledger entry.
credit_block	JSONB	The associated credit block for this entry
currency	string	The currency of the credit ledger entry.
customer	JSONB	The customer record associated with this entry.
description	nullable string	An optional description of the entry.
starting_balance	string	The beginning balance of the ledger.
ending_balance	string	The ending balance of the ledger.
entry_status	string	The status of the ledger entry.
entry_type	string	The type of the ledger entry.
invoice_id	nullable string	If set, the relevant invoice this entry applies to.
invoice_line_item_id	nullable string	If set, the relevant invoice line item ID this entry applies to.
ledger_sequence_number	integer	The sequence number of the ledger entry.
metadata	nullable JSON	If set, the metadata attached to this ledger entry.
new_block_expiry_date	nullable timestamp	If set, the time at which this expiry has been updated to.
price_id	nullable string	If set, the relevant price identifier.
void_amount	nullable string	If set, the amount of the increment that was voided.
void_reason	nullable string	If set, the reason for the increment being voided.

​

Credit note

​

Overview

The Credit note resource type 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.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Credit Note Line Item

​

Overview

The Credit Note Line Item resource type 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.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

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
id	string	The ID of the resource.
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.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Daily Line Item Revenue

​

Overview

The Daily Line Item Revenue resource type can be used to track the daily quantity and associated costs for invoice line items. This resource type 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 type is conceptually an append only resource type. 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 type 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 type 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 type 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 type is conceptually an append only resource type. 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 type 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 type 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.

​

Invoice Metadata

​

Overview

The Invoice Metadata resource represents a subset of data from the invoice resource. This resource also exposes draft invoices within Orb, which can be deleted at any time.

​

Schema

Field Name	Type	Description
id	string	The ID of the invoice.
updated_at	timestamp	The last updated date of the invoice.
created_at	timestamp	The creation time of the resource in Orb.
currency	string	The currency of the invoice.
customer_id	string	The ID of the customer.
deleted_at	nullable timestamp	The time the invoice was deleted at.
due_date	nullable timestamp	The time the invoice must be paid by.
invoice_date	timestamp	An optional invoice date set on creation.
invoice_number	nullable string	The identifying invoice number.
invoice_type	string	The type of invoice, either “one_off” or “subscription”.
issued_at	nullable timestamp	The time the invoice was sent out.
memo	nullable string	The optional memo for the reason for the invoice.
paid_at	nullable timestamp	The time that the invoice was paid.
plan_id	nullable string	The ID of the plan. Note that it may not always be present due to things like one-off invoices.
status	string	The current status indicator for the invoice.
subscription_id	nullable string	The ID of the subscription.
total	decimal	The total value for the invoice.
voided_at	nullable timestamp	The time the invoice was voided.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Item

​

Overview

The Item resource type 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
id	string	The ID of the resource.
name	string	The name of the item.
external_connections	JSONB An array of dictionaries with: external_connection_name and external_entity_id	A list of connections to external third-party providers, including provider names and external entity IDs.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Price

​

Overview

The price resource represents a price that can be associated with a plan, subscription, or invoice. See the Price configuration for more information. The price table is most useful when joining with other tables using the price_id field. For example,

• you can see price_id used in the Daily Line Item Revenue schema above to understand which price configuration generated specific revenue entries.
• you can see price_id used in the Invoice Line Item Billing schema above to understand which price configuration generated specific invoice line item values.

​

Schema

Field Name	Type	Description
id	string	The ID of the resource.
created_at	timestamp	When the price was created.
name	string	The name of the price.
external_price_id	nullable string	The ID of the price in the external system.
price_type	string	The type of price. Can be either “usage_price” or “fixed_price”.
cadence	string	The cadence of the price. Can be “one-time”, “monthly”, “quarterly”, “semi-annual”, “annual”, or “custom”.
billing_mode	string	The billing mode of the price. Can be “in_advance” or “in_arrear”.
billing_cycle_duration	nullable decimal	The duration of the billing cycle.
billing_cycle_duration_unit	string	The unit of the billing cycle duration. Can be “day” or “month”.
invoicing_cycle_duration	nullable decimal	The duration of the invoicing cycle.
invoicing_cycle_duration_unit	nullable string	The unit of the invoicing cycle duration. Can be “day” or “month”.
billable_metric_id	nullable string	The ID of the billable metric. This is only present if the price is usage based.
fixed_price_quantity	nullable decimal	The quantity of the price. This is only present if the price is fixed.
currency	string	The currency of the price.
conversion_rate	nullable decimal	The conversion rate of the price.
item_id	string	The ID of the item.
credit_allocation	nullable JSON	The credit allocation of the price.
model_type	string	The model type of the price. Can be “tiered”, “volume”, “matrix”, “tier_volume”, etc. See Price configuration for the full list.
rating_config	JSON	The rating configuration of the price.
plan_id	nullable string	The ID of the plan, if the price is associated with a plan.
plan_phase_order	nullable int	The order of the plan phase, if the price is associated with a plan and phase.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.

​

Price Interval

​

Overview

The price interval resource represents a time frame during which a price applies to a subscription. See modifying subscriptions and add or edit price intervals for more information.

​

Schema

Field Name	Type	Description
id	string	The ID of the resource.
subscription_id	string	The ID of the subscription.
customer_id	string	The ID of the customer.
price_id	string	The ID of the price.
start_date_inclusive	timestamp	The start date of the price interval.
end_date_exclusive	nullable timestamp	The end date of the price interval, if defined.
billing_cycle_day	number	The day of the billing cycle.
deleted_at	nullable timestamp	Deletion marker for this resource. If not null, then the resource has been deleted as of the time set.