API documentation
Alert
Credit
- GETFetch credit block
- DELDelete credit block
- GETFetch customer credit balance by external customer id
- GETFetch customer credits ledger by external ID
- POSTCreate ledger entry by external ID
- GETList top-ups by external ID
- POSTCreate top-up by external ID
- DELDeactivate top-up by external ID
- GETFetch customer credit balance
- GETFetch customer credits ledger
- POSTCreate ledger entry
- GETList top-ups
- POSTCreate top-up
- DELDeactivate top-up
Customer
- GETList customers
- POSTCreate customer
- GETFetch customer by external ID
- PUTUpdate customer by external ID
- GETFetch customer costs by external ID
- POSTUpdate payment methods from payment provider
- GETFetch customer
- PUTUpdate customer
- DELDelete customer
- GETList balance transactions
- POSTCreate customer balance transaction
- GETFetch customer costs
- POSTUpdate payment methods from payment provider
Dimensional Price Group
Event
Invoice
Availability
Plan
- GETList plans
- POSTCreate plan
- GETFetch plan by external ID
- PUTUpdate plan by external ID
- POSTSet plan version as default by external ID
- POSTCreate plan version by external ID
- GETFetch plan version by external ID
- GETFetch plan
- PUTUpdate plan by id
- GETList migrations
- GETFetch migration
- POSTCancel migration
- POSTSet plan version as default
- POSTCreate plan version
- GETFetch plan version
Price
Subscription Change
Subscription
- GETList subscriptions
- POSTCreate subscription
- GETFetch subscription
- PUTUpdate subscription
- POSTCancel subscription
- GETFetch subscription costs
- POSTRedeem Coupon
- GETFetch subscription schedule
- POSTSchedule plan change
- POSTTrigger phase
- POSTUnschedule subscription cancellation
- POSTUnschedule fixed fee quantity updates
- POSTUnschedule plan change
- POSTUpdate price quantity
- POSTUpdate trial for subscription
- GETFetch subscription usage
Price interval
curl --request GET \
--url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/ledger \
--header 'Authorization: Bearer <token>'{
"data": [
{
"metadata": {},
"id": "<string>",
"ledger_sequence_number": 123,
"entry_status": "committed",
"customer": {
"id": "<string>",
"external_customer_id": "<string>"
},
"starting_balance": 123,
"ending_balance": 123,
"amount": 123,
"currency": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"credit_block": {
"id": "<string>",
"expiry_date": "2023-11-07T05:31:56Z",
"per_unit_cost_basis": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"entry_type": "increment",
"created_invoices": [
{
"metadata": {},
"voided_at": "2023-11-07T05:31:56Z",
"paid_at": "2023-11-07T05:31:56Z",
"issued_at": "2023-11-07T05:31:56Z",
"scheduled_issue_at": "2023-11-07T05:31:56Z",
"auto_collection": {
"next_attempt_at": "2023-11-07T05:31:56Z",
"previously_attempted_at": "2023-11-07T05:31:56Z",
"enabled": true,
"num_attempts": 123
},
"issue_failed_at": "2023-11-07T05:31:56Z",
"sync_failed_at": "2023-11-07T05:31:56Z",
"payment_failed_at": "2023-11-07T05:31:56Z",
"payment_started_at": "2023-11-07T05:31:56Z",
"amount_due": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"currency": "<string>",
"customer": {
"id": "<string>",
"external_customer_id": "<string>"
},
"due_date": "2022-05-30T07:00:00+00:00",
"id": "<string>",
"invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
"invoice_number": "<string>",
"subscription": {
"id": "<string>"
},
"total": "<string>",
"customer_balance_transactions": [
{
"id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"starting_balance": "<string>",
"ending_balance": "<string>",
"amount": "<string>",
"action": "applied_to_invoice",
"description": "An optional description",
"invoice": {
"id": "<string>"
},
"type": "increment",
"credit_note": {
"id": "<string>"
}
}
],
"status": "issued",
"invoice_source": "subscription",
"shipping_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"billing_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"hosted_invoice_url": "<string>",
"will_auto_issue": true,
"eligible_to_issue_at": "2023-11-07T05:31:56Z",
"customer_tax_id": {
"country": "AD",
"type": "ad_nrt",
"value": "<string>"
},
"memo": "<string>",
"credit_notes": [
{
"id": "<string>",
"credit_note_number": "<string>",
"reason": "<string>",
"total": "<string>",
"voided_at": "2022-05-01T07:01:31+00:00",
"type": "<string>",
"memo": "<string>"
}
],
"payment_attempts": [
{
"id": "<string>",
"payment_provider": "stripe",
"payment_provider_id": "<string>",
"amount": "<string>",
"succeeded": true,
"created_at": "2023-11-07T05:31:56Z",
"receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
}
],
"discount": "<unknown>",
"discounts": [
{
"discount_type": "percentage",
"percentage_discount": 0.5,
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>"
}
],
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"maximum_amount": "<string>",
"line_items": [
{
"amount": "<string>",
"end_date": "2023-11-07T05:31:56Z",
"grouping": "<string>",
"adjustments": [
{
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
],
"reason": "<string>",
"replaces_adjustment_id": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"amount": "<string>"
}
],
"name": "<string>",
"quantity": 123,
"start_date": "2023-11-07T05:31:56Z",
"subtotal": "<string>",
"adjusted_subtotal": "<string>",
"credits_applied": "<string>",
"partially_invoiced_amount": "<string>",
"sub_line_items": [
{
"amount": "<string>",
"name": "<string>",
"quantity": 123,
"grouping": {
"key": "<string>",
"value": "west"
},
"type": "matrix",
"matrix_config": {
"dimension_values": [
"<string>"
]
},
"scaled_quantity": 123
}
],
"tax_amounts": [
{
"tax_rate_description": "<string>",
"tax_rate_percentage": "<string>",
"amount": "<string>"
}
],
"id": "<string>",
"price": {
"model_type": "unit",
"unit_config": {
"unit_amount": "<string>",
"prorated": false
},
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"replaces_price_id": "<string>",
"price_type": "usage_price",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_mode": "in_advance",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"conversion_rate_config": {
"conversion_rate_type": "unit",
"unit_config": {
"unit_amount": "<string>"
}
},
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true,
"custom_expiration": {
"duration": 123,
"duration_unit": "day"
},
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"composite_price_filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"discount": {
"discount_type": "percentage",
"percentage_discount": 0.5,
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"filters": "<unknown>",
"reason": "<unknown>"
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"maximum_amount": "<string>",
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
}
},
"usage_customer_ids": [
"<string>"
],
"filter": "<string>"
}
],
"subtotal": "<string>",
"invoice_date": "2023-11-07T05:31:56Z"
}
]
}
],
"pagination_metadata": {
"has_more": true,
"next_cursor": "<string>"
}
}Fetch customer credits ledger by external ID
The credits ledger provides auditing functionality over Orb’s credits system with a list of actions that have taken place to modify a customer’s credit balance. This paginated endpoint lists these entries, starting from the most recent ledger entry.
More details on using Orb’s real-time credit feature are here.
There are four major types of modifications to credit balance, detailed below.
Increment
Credits (which optionally expire on a future date) can be added via the API (Add Ledger Entry). The ledger entry for such an action will always contain the total eligible starting and ending balance for the customer at the time the entry was added to the ledger.
Decrement
Deductions can occur as a result of an API call to create a ledger entry (see
Add Ledger Entry), or automatically as a result of incurring usage. Both ledger entries
present the decrement entry type.
As usage for a customer is reported into Orb, credits may be deducted according to the customer’s plan
configuration. An automated deduction of this type will result in a ledger entry, also with a starting and ending
balance. In order to provide better tracing capabilities for automatic deductions, Orb always associates each
automatic deduction with the event_id at the time of ingestion, used to pinpoint why credit deduction took
place and to ensure that credits are never deducted without an associated usage event.
By default, Orb uses an algorithm that automatically deducts from the soonest expiring credit block first in order to ensure that all credits are utilized appropriately. As an example, if trial credits with an expiration date of 2 weeks from now are present for a customer, they will be used before any deductions take place from a non-expiring credit block.
If there are multiple blocks with the same expiration date, Orb will deduct from the block with the lower cost basis first (e.g. trial credits with a $0 cost basis before paid credits with a $5.00 cost basis).
It’s also possible for a single usage event’s deduction to span credit blocks. In this case, Orb will deduct from the next block, ending at the credit block which consists of unexpiring credits. Each of these deductions will lead to a separate ledger entry, one per credit block that is deducted from. By default, the customer’s total credit balance in Orb can be negative as a result of a decrement.
Expiration change
The expiry of credits can be changed as a result of the API (See Add Ledger Entry). This will create a ledger entry that specifies the balance as well as the initial and target expiry dates.
Note that for this entry type, starting_balance will equal ending_balance, and the amount represents the
balance transferred. The credit block linked to the ledger entry is the source credit block from which there was an
expiration change.
Credits expiry
When a set of credits expire on pre-set expiration date, the customer’s balance automatically reflects this change and adds an entry to the ledger indicating this event. Note that credit expiry should always happen close to a date boundary in the customer’s timezone.
Void initiated
Credit blocks can be voided via the API. The amount on this entry corresponds to the number of credits that were
remaining in the block at time of void. void_reason will be populated if the void is created with a reason.
Void
When a set of credits is voided, the customer’s balance automatically reflects this change and adds an entry to the ledger indicating this event.
Amendment
When credits are added to a customer’s balance as a result of a correction, this entry will be added to the ledger to indicate the adjustment of credits.
curl --request GET \
--url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/ledger \
--header 'Authorization: Bearer <token>'{
"data": [
{
"metadata": {},
"id": "<string>",
"ledger_sequence_number": 123,
"entry_status": "committed",
"customer": {
"id": "<string>",
"external_customer_id": "<string>"
},
"starting_balance": 123,
"ending_balance": 123,
"amount": 123,
"currency": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"credit_block": {
"id": "<string>",
"expiry_date": "2023-11-07T05:31:56Z",
"per_unit_cost_basis": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"entry_type": "increment",
"created_invoices": [
{
"metadata": {},
"voided_at": "2023-11-07T05:31:56Z",
"paid_at": "2023-11-07T05:31:56Z",
"issued_at": "2023-11-07T05:31:56Z",
"scheduled_issue_at": "2023-11-07T05:31:56Z",
"auto_collection": {
"next_attempt_at": "2023-11-07T05:31:56Z",
"previously_attempted_at": "2023-11-07T05:31:56Z",
"enabled": true,
"num_attempts": 123
},
"issue_failed_at": "2023-11-07T05:31:56Z",
"sync_failed_at": "2023-11-07T05:31:56Z",
"payment_failed_at": "2023-11-07T05:31:56Z",
"payment_started_at": "2023-11-07T05:31:56Z",
"amount_due": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"currency": "<string>",
"customer": {
"id": "<string>",
"external_customer_id": "<string>"
},
"due_date": "2022-05-30T07:00:00+00:00",
"id": "<string>",
"invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
"invoice_number": "<string>",
"subscription": {
"id": "<string>"
},
"total": "<string>",
"customer_balance_transactions": [
{
"id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"starting_balance": "<string>",
"ending_balance": "<string>",
"amount": "<string>",
"action": "applied_to_invoice",
"description": "An optional description",
"invoice": {
"id": "<string>"
},
"type": "increment",
"credit_note": {
"id": "<string>"
}
}
],
"status": "issued",
"invoice_source": "subscription",
"shipping_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"billing_address": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"hosted_invoice_url": "<string>",
"will_auto_issue": true,
"eligible_to_issue_at": "2023-11-07T05:31:56Z",
"customer_tax_id": {
"country": "AD",
"type": "ad_nrt",
"value": "<string>"
},
"memo": "<string>",
"credit_notes": [
{
"id": "<string>",
"credit_note_number": "<string>",
"reason": "<string>",
"total": "<string>",
"voided_at": "2022-05-01T07:01:31+00:00",
"type": "<string>",
"memo": "<string>"
}
],
"payment_attempts": [
{
"id": "<string>",
"payment_provider": "stripe",
"payment_provider_id": "<string>",
"amount": "<string>",
"succeeded": true,
"created_at": "2023-11-07T05:31:56Z",
"receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
}
],
"discount": "<unknown>",
"discounts": [
{
"discount_type": "percentage",
"percentage_discount": 0.5,
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>"
}
],
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"maximum_amount": "<string>",
"line_items": [
{
"amount": "<string>",
"end_date": "2023-11-07T05:31:56Z",
"grouping": "<string>",
"adjustments": [
{
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
],
"reason": "<string>",
"replaces_adjustment_id": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"amount": "<string>"
}
],
"name": "<string>",
"quantity": 123,
"start_date": "2023-11-07T05:31:56Z",
"subtotal": "<string>",
"adjusted_subtotal": "<string>",
"credits_applied": "<string>",
"partially_invoiced_amount": "<string>",
"sub_line_items": [
{
"amount": "<string>",
"name": "<string>",
"quantity": 123,
"grouping": {
"key": "<string>",
"value": "west"
},
"type": "matrix",
"matrix_config": {
"dimension_values": [
"<string>"
]
},
"scaled_quantity": 123
}
],
"tax_amounts": [
{
"tax_rate_description": "<string>",
"tax_rate_percentage": "<string>",
"amount": "<string>"
}
],
"id": "<string>",
"price": {
"model_type": "unit",
"unit_config": {
"unit_amount": "<string>",
"prorated": false
},
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"replaces_price_id": "<string>",
"price_type": "usage_price",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_mode": "in_advance",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"conversion_rate_config": {
"conversion_rate_type": "unit",
"unit_config": {
"unit_amount": "<string>"
}
},
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true,
"custom_expiration": {
"duration": 123,
"duration_unit": "day"
},
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"composite_price_filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"discount": {
"discount_type": "percentage",
"percentage_discount": 0.5,
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"filters": "<unknown>",
"reason": "<unknown>"
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"applies_to_price_ids": [
"<string>"
]
},
"maximum_amount": "<string>",
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
}
},
"usage_customer_ids": [
"<string>"
],
"filter": "<string>"
}
],
"subtotal": "<string>",
"invoice_date": "2023-11-07T05:31:56Z"
}
]
}
],
"pagination_metadata": {
"has_more": true,
"next_cursor": "<string>"
}
}Authorizations
API Keys can be issued in the Orb's web application.
Path Parameters
Query Parameters
The number of items to fetch. Defaults to 20.
1 <= x <= 100Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
The ledger currency or custom pricing unit to use.
increment, decrement, expiration_change, credit_block_expiry, void, void_initiated, amendment committed, pending Response
OK
The Credit Ledger Entry resource models prepaid credits within Orb.
- IncrementLedgerEntry
- DecrementLedgerEntry
- ExpirationChangeLedgerEntry
- CreditBlockExpiryLedgerEntry
- VoidLedgerEntry
- VoidInitiatedLedgerEntry
- AmendmentLedgerEntry
Show child attributes
Show child attributes
User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
Show child attributes
Show child attributes
committed, pending Show child attributes
Show child attributes
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
increment If the increment resulted in invoice creation, the list of created invoices
Show child attributes
Show child attributes
User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
Show child attributes
Show child attributes
If the invoice has a status of void, this gives a timestamp when the invoice was voided.
If the invoice has a status of paid, this gives a timestamp when the invoice was paid.
If the invoice has been issued, this will be the time it transitioned to issued (even if it is now in a different state.)
If the invoice is in draft, this timestamp will reflect when the invoice is scheduled to be issued.
Show child attributes
Show child attributes
If the invoice is scheduled for auto-collection, this field will reflect when the next attempt will occur. If dunning has been exhausted, or auto-collection is not enabled for this invoice, this field will be null.
If Orb has ever attempted payment auto-collection for this invoice, this field will reflect when that attempt occurred. In conjunction with next_attempt_at, this can be used to tell whether the invoice is currently in dunning (that is, previously_attempted_at is non-null, and next_attempt_time is non-null), or if dunning has been exhausted (previously_attempted_at is non-null, but next_attempt_time is null).
True only if auto-collection is enabled for this invoice.
Number of auto-collection payment attempts.
If the invoice failed to issue, this will be the last time it failed to issue (even if it is now in a different state.)
If the invoice failed to sync, this will be the last time an external invoicing provider sync was attempted. This field will always be null for invoices using Orb Invoicing.
If payment was attempted on this invoice but failed, this will be the time of the most recent attempt.
If payment was attempted on this invoice, this will be the start time of the most recent attempt. This field is especially useful for delayed-notification payment mechanisms (like bank transfers), where payment can take 3 days or more.
This is the final amount required to be charged to the customer and reflects the application of the customer balance to the total of the invoice.
The creation time of the resource in Orb.
An ISO 4217 currency string or credits
When the invoice payment is due. The due date is null if the invoice is not yet finalized.
"2022-05-30T07:00:00+00:00"
The link to download the PDF representation of the Invoice.
"https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
Automatically generated invoice number to help track and reconcile invoices. Invoice numbers have a prefix such as RFOBWG. These can be sequential per account or customer.
The total after any minimums and discounts have been applied.
Show child attributes
Show child attributes
A unique id for this transaction.
The creation time of this transaction.
The original value of the customer's balance prior to the transaction, in the customer's currency.
The new value of the customer's balance prior to the transaction, in the customer's currency.
The value of the amount changed in the transaction.
applied_to_invoice, manual_adjustment, prorated_refund, revert_prorated_refund, return_from_voiding, credit_note_applied, credit_note_voided, overpayment_refund, external_payment, small_invoice_carryover An optional description provided for manual customer balance adjustments.
"An optional description"
increment, decrement issued, paid, synced, void, draft subscription, partial, one_off Show child attributes
Show child attributes
Show child attributes
Show child attributes
A URL for the customer-facing invoice portal. This URL expires 30 days after the invoice's due date, or 60 days after being re-generated through the UI.
This is true if the invoice will be automatically issued in the future, and false otherwise.
If the invoice has a status of draft, this will be the time that the invoice will be eligible to be issued, otherwise it will be null. If auto-issue is true, the invoice will automatically begin issuing at this time.
Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
Supported Tax ID Countries and Types
| Country | Type | Description |
|---|---|---|
| Albania | al_tin | Albania Tax Identification Number |
| Andorra | ad_nrt | Andorran NRT Number |
| Angola | ao_tin | Angola Tax Identification Number |
| Argentina | ar_cuit | Argentinian Tax ID Number |
| Armenia | am_tin | Armenia Tax Identification Number |
| Aruba | aw_tin | Aruba Tax Identification Number |
| Australia | au_abn | Australian Business Number (AU ABN) |
| Australia | au_arn | Australian Taxation Office Reference Number |
| Austria | eu_vat | European VAT Number |
| Azerbaijan | az_tin | Azerbaijan Tax Identification Number |
| Bahamas | bs_tin | Bahamas Tax Identification Number |
| Bahrain | bh_vat | Bahraini VAT Number |
| Bangladesh | bd_bin | Bangladesh Business Identification Number |
| Barbados | bb_tin | Barbados Tax Identification Number |
| Belarus | by_tin | Belarus TIN Number |
| Belgium | eu_vat | European VAT Number |
| Benin | bj_ifu | Benin Tax Identification Number (Identifiant Fiscal Unique) |
| Bolivia | bo_tin | Bolivian Tax ID |
| Bosnia and Herzegovina | ba_tin | Bosnia and Herzegovina Tax Identification Number |
| Brazil | br_cnpj | Brazilian CNPJ Number |
| Brazil | br_cpf | Brazilian CPF Number |
| Bulgaria | bg_uic | Bulgaria Unified Identification Code |
| Bulgaria | eu_vat | European VAT Number |
| Burkina Faso | bf_ifu | Burkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique) |
| Cambodia | kh_tin | Cambodia Tax Identification Number |
| Cameroon | cm_niu | Cameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique) |
| Canada | ca_bn | Canadian BN |
| Canada | ca_gst_hst | Canadian GST/HST Number |
| Canada | ca_pst_bc | Canadian PST Number (British Columbia) |
| Canada | ca_pst_mb | Canadian PST Number (Manitoba) |
| Canada | ca_pst_sk | Canadian PST Number (Saskatchewan) |
| Canada | ca_qst | Canadian QST Number (Québec) |
| Cape Verde | cv_nif | Cape Verde Tax Identification Number (Número de Identificação Fiscal) |
| Chile | cl_tin | Chilean TIN |
| China | cn_tin | Chinese Tax ID |
| Colombia | co_nit | Colombian NIT Number |
| Congo-Kinshasa | cd_nif | Congo (DR) Tax Identification Number (Número de Identificação Fiscal) |
| Costa Rica | cr_tin | Costa Rican Tax ID |
| Croatia | eu_vat | European VAT Number |
| Croatia | hr_oib | Croatian Personal Identification Number (OIB) |
| Cyprus | eu_vat | European VAT Number |
| Czech Republic | eu_vat | European VAT Number |
| Denmark | eu_vat | European VAT Number |
| Dominican Republic | do_rcn | Dominican RCN Number |
| Ecuador | ec_ruc | Ecuadorian RUC Number |
| Egypt | eg_tin | Egyptian Tax Identification Number |
| El Salvador | sv_nit | El Salvadorian NIT Number |
| Estonia | eu_vat | European VAT Number |
| Ethiopia | et_tin | Ethiopia Tax Identification Number |
| European Union | eu_oss_vat | European One Stop Shop VAT Number for non-Union scheme |
| Finland | eu_vat | European VAT Number |
| France | eu_vat | European VAT Number |
| Georgia | ge_vat | Georgian VAT |
| Germany | de_stn | German Tax Number (Steuernummer) |
| Germany | eu_vat | European VAT Number |
| Greece | eu_vat | European VAT Number |
| Guinea | gn_nif | Guinea Tax Identification Number (Número de Identificação Fiscal) |
| Hong Kong | hk_br | Hong Kong BR Number |
| Hungary | eu_vat | European VAT Number |
| Hungary | hu_tin | Hungary Tax Number (adószám) |
| Iceland | is_vat | Icelandic VAT |
| India | in_gst | Indian GST Number |
| Indonesia | id_npwp | Indonesian NPWP Number |
| Ireland | eu_vat | European VAT Number |
| Israel | il_vat | Israel VAT |
| Italy | eu_vat | European VAT Number |
| Japan | jp_cn | Japanese Corporate Number (Hōjin Bangō) |
| Japan | jp_rn | Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō) |
| Japan | jp_trn | Japanese Tax Registration Number (Tōroku Bangō) |
| Kazakhstan | kz_bin | Kazakhstani Business Identification Number |
| Kenya | ke_pin | Kenya Revenue Authority Personal Identification Number |
| Kyrgyzstan | kg_tin | Kyrgyzstan Tax Identification Number |
| Laos | la_tin | Laos Tax Identification Number |
| Latvia | eu_vat | European VAT Number |
| Liechtenstein | li_uid | Liechtensteinian UID Number |
| Liechtenstein | li_vat | Liechtenstein VAT Number |
| Lithuania | eu_vat | European VAT Number |
| Luxembourg | eu_vat | European VAT Number |
| Malaysia | my_frp | Malaysian FRP Number |
| Malaysia | my_itn | Malaysian ITN |
| Malaysia | my_sst | Malaysian SST Number |
| Malta | eu_vat | European VAT Number |
| Mauritania | mr_nif | Mauritania Tax Identification Number (Número de Identificação Fiscal) |
| Mexico | mx_rfc | Mexican RFC Number |
| Moldova | md_vat | Moldova VAT Number |
| Montenegro | me_pib | Montenegro PIB Number |
| Morocco | ma_vat | Morocco VAT Number |
| Nepal | np_pan | Nepal PAN Number |
| Netherlands | eu_vat | European VAT Number |
| New Zealand | nz_gst | New Zealand GST Number |
| Nigeria | ng_tin | Nigerian Tax Identification Number |
| North Macedonia | mk_vat | North Macedonia VAT Number |
| Northern Ireland | eu_vat | Northern Ireland VAT Number |
| Norway | no_vat | Norwegian VAT Number |
| Norway | no_voec | Norwegian VAT on e-commerce Number |
| Oman | om_vat | Omani VAT Number |
| Peru | pe_ruc | Peruvian RUC Number |
| Philippines | ph_tin | Philippines Tax Identification Number |
| Poland | eu_vat | European VAT Number |
| Portugal | eu_vat | European VAT Number |
| Romania | eu_vat | European VAT Number |
| Romania | ro_tin | Romanian Tax ID Number |
| Russia | ru_inn | Russian INN |
| Russia | ru_kpp | Russian KPP |
| Saudi Arabia | sa_vat | Saudi Arabia VAT |
| Senegal | sn_ninea | Senegal NINEA Number |
| Serbia | rs_pib | Serbian PIB Number |
| Singapore | sg_gst | Singaporean GST |
| Singapore | sg_uen | Singaporean UEN |
| Slovakia | eu_vat | European VAT Number |
| Slovenia | eu_vat | European VAT Number |
| Slovenia | si_tin | Slovenia Tax Number (davčna številka) |
| South Africa | za_vat | South African VAT Number |
| South Korea | kr_brn | Korean BRN |
| Spain | es_cif | Spanish NIF Number (previously Spanish CIF Number) |
| Spain | eu_vat | European VAT Number |
| Suriname | sr_fin | Suriname FIN Number |
| Sweden | eu_vat | European VAT Number |
| Switzerland | ch_uid | Switzerland UID Number |
| Switzerland | ch_vat | Switzerland VAT Number |
| Taiwan | tw_vat | Taiwanese VAT |
| Tajikistan | tj_tin | Tajikistan Tax Identification Number |
| Tanzania | tz_vat | Tanzania VAT Number |
| Thailand | th_vat | Thai VAT |
| Turkey | tr_tin | Turkish Tax Identification Number |
| Uganda | ug_tin | Uganda Tax Identification Number |
| Ukraine | ua_vat | Ukrainian VAT |
| United Arab Emirates | ae_trn | United Arab Emirates TRN |
| United Kingdom | gb_vat | United Kingdom VAT Number |
| United States | us_ein | United States EIN |
| Uruguay | uy_ruc | Uruguayan RUC Number |
| Uzbekistan | uz_tin | Uzbekistan TIN Number |
| Uzbekistan | uz_vat | Uzbekistan VAT Number |
| Venezuela | ve_rif | Venezuelan RIF Number |
| Vietnam | vn_tin | Vietnamese Tax ID Number |
| Zambia | zm_tin | Zambia Tax Identification Number |
| Zimbabwe | zw_tin | Zimbabwe Tax Identification Number |
Show child attributes
Show child attributes
AD, AE, AL, AM, AO, AR, AT, AU, AW, AZ, BA, BB, BD, BE, BF, BG, BH, BJ, BO, BR, BS, BY, CA, CD, CH, CL, CM, CN, CO, CR, CV, DE, CY, CZ, DK, DO, EC, EE, EG, ES, ET, EU, FI, FR, GB, GE, GN, GR, HK, HR, HU, ID, IE, IL, IN, IS, IT, JP, KE, KG, KH, KR, KZ, LA, LI, LT, LU, LV, MA, MD, ME, MK, MR, MT, MX, MY, NG, NL, NO, NP, NZ, OM, PE, PH, PL, PT, RO, RS, RU, SA, SE, SG, SI, SK, SN, SR, SV, TH, TJ, TR, TW, TZ, UA, UG, US, UY, UZ, VE, VN, ZA, ZM, ZW ad_nrt, ae_trn, al_tin, am_tin, ao_tin, ar_cuit, eu_vat, au_abn, au_arn, aw_tin, az_tin, ba_tin, bb_tin, bd_bin, bf_ifu, bg_uic, bh_vat, bj_ifu, bo_tin, br_cnpj, br_cpf, bs_tin, by_tin, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, cd_nif, ch_uid, ch_vat, cl_tin, cm_niu, cn_tin, co_nit, cr_tin, cv_nif, de_stn, do_rcn, ec_ruc, eg_tin, es_cif, et_tin, eu_oss_vat, gb_vat, ge_vat, gn_nif, hk_br, hr_oib, hu_tin, id_npwp, il_vat, in_gst, is_vat, jp_cn, jp_rn, jp_trn, ke_pin, kg_tin, kh_tin, kr_brn, kz_bin, la_tin, li_uid, li_vat, ma_vat, md_vat, me_pib, mk_vat, mr_nif, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, np_pan, nz_gst, om_vat, pe_ruc, ph_tin, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sn_ninea, sr_fin, sv_nit, th_vat, tj_tin, tr_tin, tw_vat, tz_vat, ua_vat, ug_tin, us_ein, uy_ruc, uz_tin, uz_vat, ve_rif, vn_tin, za_vat, zm_tin, zw_tin Free-form text which is available on the invoice PDF and the Orb invoice portal.
A list of credit notes associated with the invoice
Show child attributes
Show child attributes
If the credit note has a status of void, this gives a timestamp when the credit note was voided.
"2022-05-01T07:01:31+00:00"
An optional memo supplied on the credit note.
A list of payment attempts associated with the invoice
Show child attributes
Show child attributes
The ID of the payment attempt.
The payment provider that attempted to collect the payment.
stripe The ID of the payment attempt in the payment provider.
The amount of the payment attempt.
Whether the payment attempt succeeded.
The time at which the payment attempt was created.
URL to the downloadable PDF version of the receipt. This field will be null for payment attempts that did not succeed.
"https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
This field is deprecated in favor of discounts. If a discounts list is provided, the first discount in the list will be returned. If the list is empty, None will be returned.
- PercentageDiscount
- AmountDiscount
- TrialDiscount
Show child attributes
Show child attributes
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 <= x <= 1List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]The filters that determine which prices to apply this discount to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
Show child attributes
Show child attributes
Minimum amount applied
The filters that determine which prices to apply this minimum to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
Show child attributes
Show child attributes
Maximum amount applied
The filters that determine which prices to apply this maximum to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
The breakdown of prices in this invoice.
Show child attributes
Show child attributes
The final amount for a line item after all adjustments and pre paid credits have been applied.
The end date of the range of time applied for this line item's price.
[DEPRECATED] For configured prices that are split by a grouping key, this will be populated with the key and a value. The amount and subtotal will be the values for this particular grouping.
All adjustments applied to the line item in the order they were applied based on invoice calculations (ie. usage discounts -> amount discounts -> percentage discounts -> minimums -> maximums).
- MonetaryUsageDiscountAdjustment
- MonetaryAmountDiscountAdjustment
- MonetaryPercentageDiscountAdjustment
- MonetaryMinimumAdjustment
- MonetaryMaximumAdjustment
Show child attributes
Show child attributes
True for adjustments that apply to an entire invoice, false for adjustments that apply to only one price.
The filters that determine which prices to apply this adjustment to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
The price IDs that this adjustment applies to.
The reason for the adjustment.
The adjustment id this adjustment replaces. This adjustment will take the place of the replaced adjustment in plan version migrations.
usage_discount The number of usage units by which to discount the price this adjustment applies to in a given billing period.
The value applied by an adjustment.
The name of the price associated with this line item.
Either the fixed fee quantity or the usage during the service period.
The start date of the range of time applied for this line item's price.
The line amount before any adjustments.
The line amount after any adjustments and before overage conversion, credits and partial invoicing.
The number of prepaid credits applied.
Any amount applied from a partial invoice
For complex pricing structures, the line item can be broken down further in sub_line_items.
- MatrixSubLineItem
- TierSubLineItem
- OtherSubLineItem
Show child attributes
Show child attributes
The total amount for this sub line item.
matrix The scaled quantity for this line item for specific pricing structures
An array of tax rates and their incurred tax amounts. Empty if no tax integration is configured.
Show child attributes
Show child attributes
The human-readable description of the applied tax rate.
The tax rate percentage, out of 100.
The amount of additional tax incurred by this tax rate.
A unique ID for this line item.
The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.
Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.
For more on the types of prices, see the core concepts documentation
- UnitPrice
- TieredPrice
- BulkPrice
- BulkWithFiltersPrice
- PackagePrice
- MatrixPrice
- ThresholdTotalAmountPrice
- TieredPackagePrice
- TieredWithMinimumPrice
- GroupedTieredPrice
- TieredPackageWithMinimumPrice
- PackageWithAllocationPrice
- UnitWithPercentPrice
- MatrixWithAllocationPrice
- TieredWithProrationPrice
- UnitWithProrationPrice
- GroupedAllocationPrice
- BulkWithProrationPrice
- GroupedWithProratedMinimumPrice
- GroupedWithMeteredMinimumPrice
- GroupedWithMinMaxThresholdsPrice
- MatrixWithDisplayNamePrice
- GroupedTieredPackagePrice
- MaxGroupTieredPackagePrice
- ScalableMatrixWithUnitPricingPrice
- ScalableMatrixWithTieredPricingPrice
- CumulativeGroupedBulkPrice
- CumulativeGroupedAllocationPrice
- MinimumCompositePrice
- PercentCompositePrice
- EventOutputPrice
Show child attributes
Show child attributes
The pricing model type
unit Configuration for unit pricing
User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
Show child attributes
Show child attributes
The price id this price replaces. This price will take the place of the replaced price in plan version migrations.
usage_price, fixed_price, composite_price one_time, monthly, quarterly, semi_annual, annual, custom in_advance, in_arrear - UnitConversionRateConfig
- TieredConversionRateConfig
Show child attributes
Show child attributes
unit A minimal representation of an Item containing only the essential identifying information.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
- PercentageDiscount
- TrialDiscount
- UsageDiscount
- AmountDiscount
Show child attributes
Show child attributes
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 <= x <= 1List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]The filters that determine which prices to apply this discount to.
Show child attributes
Show child attributes
Minimum amount applied
The filters that determine which prices to apply this minimum to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.
Show child attributes
Show child attributes
Maximum amount applied
The filters that determine which prices to apply this maximum to.
Show child attributes
Show child attributes
The property of the price to filter on.
price_id, item_id, price_type, currency, pricing_unit_id Should prices that match the filter be included or excluded.
includes, excludes The IDs or values that match this filter.
List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.
A list of customer ids that were used to calculate the usage for this line item.
An additional filter that was used to calculate the usage for this line item.
The total before any discounts and minimums are applied.
The scheduled date of the invoice
Was this page helpful?