Orb
App · 20 actions
Manage customers, subscriptions, invoices and usage events in Orb.
Actions
| Action | What it does |
|---|---|
| Cancel subscription | This endpoint can be used to cancel an existing subscription. |
| Check connection | This endpoint allows you to test your connection to the Orb API and check the validity of your API key, passed in the Authorization header. |
| Create customer | This operation is used to create an Orb customer, who is party to the core billing relationship. |
| Create subscription | A subscription represents the purchase of a plan by a customer. |
| Delete customer | This performs a deletion of this customer, its subscriptions, and its invoices, provided the customer does not have any issued invoices. |
| Get customer | This endpoint is used to fetch customer details given an identifier. |
| Get customer by external ID | This endpoint is used to fetch customer details given an external_customer_id (see Customer ID Aliases). |
| Get invoice | This endpoint is used to fetch an Invoice given an identifier. |
| Get plan | This endpoint is used to fetch plan details given a plan identifier. |
| Get subscription | This endpoint is used to fetch a Subscription given an identifier. |
| Get subscription usage | This endpoint is used to fetch a subscription's usage in Orb. |
| Get upcoming invoice | This endpoint can be used to fetch the upcoming invoice for the current billing period given a subscription. |
| List customer credit blocks | Returns a paginated list of unexpired, non-zero credit blocks for a customer. |
| List customers | This endpoint returns a list of all customers for an account. |
| List invoices | This endpoint returns a list of all Invoices for an account in a list format. |
| List plans | This endpoint returns a list of all plans for an account in a list format. |
| List prices | This endpoint is used to list all add-on prices created using the price creation endpoint. |
| List subscriptions | This endpoint returns a list of all subscriptions for an account as a paginated list, ordered starting from the most recently created subscription. |
| Send usage events | Orb's event ingestion model and API is designed around two core principles: |
| Update customer | Update the customer fields you fill in. |
Cancel subscription
This endpoint can be used to cancel an existing subscription. It returns the serialized subscription object with an end_date parameter that signifies when the subscription will transition to an ended state.
Inputs
- Subscription
subscription_idtextRequired - Subscription ID.
- Cancel option
cancel_optiontextRequired - Determines the timing of subscription cancellationOne of:
end_of_subscription_term(End of subscription term),immediate,requested_date(Requested date). - Cancellation date
cancellation_datedate and time - The date that the cancellation should take effect. This parameter can only be passed if the cancel_option is requested_date.
- Allow invoice credit or void
allow_invoice_credit_or_voidtrue/false - If false, this request will fail if it would void an issued invoice or create a credit note. Consider using this as a safety mechanism if you do not expect existing invoices to be changed.Default:
true.
Outputs
dataobject- MutatedSubscription
Example output
{
"data": {
"active_plan_phase_order": 1,
"adjustment_intervals": [],
"auto_collection": false,
"auto_issuance": false,
"billing_cycle_anchor_configuration": {
"day": 1,
"month": 1,
"year": 1
},
"billing_cycle_day": 1,
"changed_resources": {
"created_credit_notes": [],
"created_invoices": [],
"voided_credit_notes": [],
"voided_invoices": []
},
"created_at": "example",
"current_billing_period_end_date": "example",
"current_billing_period_start_date": "example",
"customer": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
},
"default_invoice_memo": "example",
"discount_intervals": [],
"end_date": "example",
"fixed_fee_quantity_schedule": [],
"id": "example",
"invoicing_threshold": "example",
"maximum_intervals": [],
"metadata": {},
"minimum_intervals": [],
"name": "example",
"net_terms": 1,
"pending_subscription_change": {
"id": "example"
},
"plan": {
"adjustments": [],
"base_plan": {},
"base_plan_id": "example",
"created_at": "example",
"currency": "example",
"default_invoice_memo": "example",
"description": "example",
"discount": {},
"external_plan_id": "example",
"has_draft": false,
"id": "example",
"invoicing_currency": "example",
"maximum": {
"applies_to_price_ids": [],
"filters": [],
"maximum_amount": "example"
},
"maximum_amount": "example",
"metadata": {},
"minimum": {
"applies_to_price_ids": [],
"filters": [],
"minimum_amount": "example"
},
"minimum_amount": "example",
"name": "example",
"net_terms": 1,
"plan_phases": [],
"prices": [],
"product": {
"created_at": "example",
"id": "example",
"name": "example"
},
"status": "example",
"trial_config": {
"trial_period": 1,
"trial_period_unit": "example"
},
"version": 1
},
"price_intervals": [],
"redeemed_coupon": {
"coupon_id": "example",
"end_date": "example",
"start_date": "example"
},
"start_date": "example",
"status": "example",
"trial_info": {
"end_date": "example"
}
}
}Check connection
This endpoint allows you to test your connection to the Orb API and check the validity of your API key, passed in the Authorization header. This is particularly useful for checking that your environment is set up properly, and is a great choice for connectors and integrations.
Inputs
None.
Outputs
dataobject- PingResponse
Example output
{
"data": {
"response": "example"
}
}Create customer
This operation is used to create an Orb customer, who is party to the core billing relationship. See Customer for an overview of the customer resource.
Inputs
- Metadata
metadataobject - User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
- Name
nametextRequired - The full name of the customer
- Email
emailtextRequired - A valid customer email, to be used for notifications. When Orb triggers payment through a payment gateway, this email will be used for any automatically issued receipts.
- Timezone
timezonetext - A timezone identifier from the IANA timezone database, such as "America/Los_Angeles". This defaults to your account's timezone if not set. This cannot be changed after customer creation.
- External customer ID
external_customer_idtext - An optional user-defined ID for this customer resource, used throughout the system as an alias for this Customer. Use this field to identify a customer by an existing identifier in your system.
- Payment provider ID
payment_provider_idtext - The ID of this customer in an external payments solution, such as Stripe. This is used for creating charges or invoices in the external system via Orb.
- Payment provider
payment_providertext - This is used for creating charges or invoices in an external system via Orb. When not in test mode, the connection must first be configured in the Orb webapp.One of:
quickbooks,bill.com,stripe_charge(Stripe charge),stripe_invoice(Stripe invoice),netsuite,adyen. - Shipping address
shipping_addressobject - AddressInput
- Billing address
billing_addressobject - AddressInput
- Currency
currencytext - An ISO 4217 currency string used for the customer's invoices and balance. If not set at creation time, will be set at subscription creation time.
- Tax ID
tax_idobject - Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
- Auto collection
auto_collectiontrue/false - Used to determine if invoices for this customer will automatically attempt to charge a saved payment method, if available. This parameter defaults to True when a payment provider is provided on customer creation.
- Auto issuance
auto_issuancetrue/false - Used to determine if invoices for this customer will be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null is specified, the customer's auto issuance setting will be inherited from the account-level…
- Email delivery
email_deliverytrue/false - Email Delivery
- Tax configuration
tax_configurationobject - Tax configuration.
- Reporting configuration
reporting_configurationobject - NewReportingConfiguration
- Accounting sync configuration
accounting_sync_configurationobject - NewAccountingSyncConfiguration
- Additional emails
additional_emailslist - Additional email addresses for this customer. If populated, these email addresses will be CC'd for customer communications. The total number of email addresses (including the primary email) cannot exceed 50.
- Hierarchy
hierarchyobject - The hierarchical relationships for this customer.
- Payment configuration
payment_configurationobject - Payment configuration for the customer, applicable when using Orb Invoicing with a supported payment provider such as Stripe.
Outputs
dataobject- A customer is a buyer of your products, and the other party to the billing relationship.
Example output
{
"data": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"external_customer_id": "example",
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
}
}Create subscription
A subscription represents the purchase of a plan by a customer. The customer is identified by either the customer_id or the external_customer_id, and exactly one of these fields must be provided.
Inputs
- Usage customer IDS
usage_customer_idslist - A list of customer IDs whose usage events will be aggregated and billed under this subscription. By default, a subscription only considers usage events associated with its attached customer's customer_id. When usage_customer_ids is provided, the subscription includes usage…
- Filter
filtertext - An additional filter to apply to usage queries. This filter must be expressed as a boolean computed property. If null, usage queries will not include any additional filter.
- Metadata
metadataobject - User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
- Plan
plan_idtext - The plan that the given subscription should be switched to. Note that either this property or external_plan_id must be specified.
- External plan ID
external_plan_idtext - The external_plan_id of the plan that the given subscription should be switched to. Note that either this property or plan_id must be specified.
- Price overrides
price_overrideslist - Optionally provide a list of overrides for prices on the plan
- Per credit overage amount
per_credit_overage_amountnumber - Per Credit Overage Amount
- Credits overage rate
credits_overage_ratenumber - Credits Overage Rate
- Trial duration days
trial_duration_daysnumber - The duration of the trial period in days. If not provided, this defaults to the value specified in the plan. If 0 is provided, the trial on the plan will be skipped.At least 0.0.
- Net terms
net_termsnumber - The net terms determines the difference between the invoice date and the issue date for the invoice. If you intend the invoice to be due on issue, set this to 0. If not provided, this defaults to the value specified in the plan.
- Auto collection
auto_collectiontrue/false - Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. If not specified, this defaults to the behavior configured for this customer.
- Auto issuance
auto_issuancetrue/false - Used to determine if invoices for this subscription will be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null is specified, this defaults to the behavior configured for this customer.
- Default invoice memo
default_invoice_memotext - Determines the default memo on this subscription's invoices. Note that if this is not provided, it is determined by the plan configuration.
- Coupon redemption code
coupon_redemption_codetext - Redemption code to be used for this subscription. If the coupon cannot be found by its redemption code, or cannot be redeemed, an error response will be returned and the subscription creation or plan change will not be scheduled.
- Invoicing threshold
invoicing_thresholdtext - When this subscription's accrued usage reaches this threshold, an invoice will be issued for the subscription. If not specified, invoices will only be issued at the end of the billing period.
- Initial phase order
initial_phase_ordernumber - The phase of the plan to start with
- Add prices
add_priceslist - Additional prices to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
- Remove prices
remove_priceslist - Plan prices to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
- Replace prices
replace_priceslist - Plan prices to be replaced with additional prices on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
- Add adjustments
add_adjustmentslist - Additional adjustments to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
- Remove adjustments
remove_adjustmentslist - Plan adjustments to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
- Replace adjustments
replace_adjustmentslist - Plan adjustments to be replaced with additional adjustments on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
- Customer
customer_idtext - Customer Id
- External customer ID
external_customer_idtext - External Customer Id
- Currency
currencytext - The currency to use for the subscription. If not specified, the invoicing currency for the plan will be used.
- Name
nametext - The name to use for the subscription. If not specified, the plan name will be used.
- Start date
start_datedate and time - Start Date
- End date
end_datedate and time - End Date
- Plan version number
plan_version_numbernumber - Specifies which version of the plan to subscribe to. If null, the default version will be used.
- External marketplace
external_marketplacetext - External MarketplaceOne of:
google,aws,azure. - External marketplace reporting ID
external_marketplace_reporting_idtext - External Marketplace Reporting Id
- Aws region
aws_regiontext - Aws Region
- Align billing with subscription start date
align_billing_with_subscription_start_datetrue/false - Align Billing With Subscription Start DateDefault:
false. - Billing cycle anchor configuration
billing_cycle_anchor_configurationobject - BillingCycleAnchorConfiguration
Outputs
dataobject- MutatedSubscription
Example output
{
"data": {
"active_plan_phase_order": 1,
"adjustment_intervals": [],
"auto_collection": false,
"auto_issuance": false,
"billing_cycle_anchor_configuration": {
"day": 1,
"month": 1,
"year": 1
},
"billing_cycle_day": 1,
"changed_resources": {
"created_credit_notes": [],
"created_invoices": [],
"voided_credit_notes": [],
"voided_invoices": []
},
"created_at": "example",
"current_billing_period_end_date": "example",
"current_billing_period_start_date": "example",
"customer": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
},
"default_invoice_memo": "example",
"discount_intervals": [],
"end_date": "example",
"fixed_fee_quantity_schedule": [],
"id": "example",
"invoicing_threshold": "example",
"maximum_intervals": [],
"metadata": {},
"minimum_intervals": [],
"name": "example",
"net_terms": 1,
"pending_subscription_change": {
"id": "example"
},
"plan": {
"adjustments": [],
"base_plan": {},
"base_plan_id": "example",
"created_at": "example",
"currency": "example",
"default_invoice_memo": "example",
"description": "example",
"discount": {},
"external_plan_id": "example",
"has_draft": false,
"id": "example",
"invoicing_currency": "example",
"maximum": {
"applies_to_price_ids": [],
"filters": [],
"maximum_amount": "example"
},
"maximum_amount": "example",
"metadata": {},
"minimum": {
"applies_to_price_ids": [],
"filters": [],
"minimum_amount": "example"
},
"minimum_amount": "example",
"name": "example",
"net_terms": 1,
"plan_phases": [],
"prices": [],
"product": {
"created_at": "example",
"id": "example",
"name": "example"
},
"status": "example",
"trial_config": {
"trial_period": 1,
"trial_period_unit": "example"
},
"version": 1
},
"price_intervals": [],
"redeemed_coupon": {
"coupon_id": "example",
"end_date": "example",
"start_date": "example"
},
"start_date": "example",
"status": "example",
"trial_info": {
"end_date": "example"
}
}
}Delete customer
This performs a deletion of this customer, its subscriptions, and its invoices, provided the customer does not have any issued invoices. Customers with issued invoices cannot be deleted. This operation is irreversible. Note that this is a soft deletion, but the data will…
Inputs
- Customer
customer_idtextRequired - Customer ID.
Outputs
dataobject- Result.
Example output
{
"data": {}
}Get customer
This endpoint is used to fetch customer details given an identifier. If the Customer is in the process of being deleted, only the properties id and deleted: true will be returned.
Inputs
- Customer
customer_idtextRequired - Customer ID.
Outputs
dataobject- A customer is a buyer of your products, and the other party to the billing relationship.
Example output
{
"data": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"external_customer_id": "example",
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
}
}Get customer by external ID
This endpoint is used to fetch customer details given an external_customer_id (see Customer ID Aliases).
Inputs
- External customer ID
external_customer_idtextRequired - External customer ID.
Outputs
dataobject- A customer is a buyer of your products, and the other party to the billing relationship.
Example output
{
"data": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"external_customer_id": "example",
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
}
}Get invoice
This endpoint is used to fetch an Invoice given an identifier.
Inputs
- Invoice
invoice_idtextRequired - Invoice ID.
- Include zero quantity line items
include_zero_quantity_line_itemstrue/false - Whether to return line items with a quantity of zero. When omitted, Orb returns every line item. A line item that is grouped as part of a line item minimum is always returned; an invoice-level minimum does not exempt it.
Outputs
dataobject- An Invoice is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated…
Example output
{
"data": {
"amount_due": "example",
"auto_collection": {
"enabled": false,
"next_attempt_at": "example",
"num_attempts": 1,
"previously_attempted_at": "example"
},
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"credit_notes": [],
"currency": "example",
"customer": {
"external_customer_id": "example",
"id": "example"
},
"customer_balance_transactions": [],
"customer_tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"discounts": [],
"due_date": "example",
"eligible_to_issue_at": "example",
"hidden_line_item_count": 1,
"hosted_invoice_url": "example",
"id": "example",
"invoice_date": "example",
"invoice_number": "example",
"invoice_pdf": "example",
"invoice_source": "example",
"issue_failed_at": "example",
"issued_at": "example",
"line_items": [],
"maximum": {
"applies_to_price_ids": [],
"filters": [],
"maximum_amount": "example"
},
"maximum_amount": "example",
"memo": "example",
"metadata": {},
"minimum": {
"applies_to_price_ids": [],
"filters": [],
"minimum_amount": "example"
},
"minimum_amount": "example",
"paid_at": "example",
"payment_attempts": [],
"payment_failed_at": "example",
"payment_received_at": "example",
"payment_started_at": "example",
"scheduled_issue_at": "example",
"service_period_end": "example",
"service_period_start": "example",
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"status": "example",
"subscription": {
"id": "example"
},
"subtotal": "example",
"sync_failed_at": "example",
"total": "example",
"voided_at": "example",
"will_auto_issue": false
}
}Get plan
This endpoint is used to fetch plan details given a plan identifier. It returns information about the prices included in the plan and their configuration, as well as the product that the plan is attached to.
Inputs
- Plan
plan_idtextRequired - Plan ID.
Outputs
dataobject- The Plan resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the Price resource.
Example output
{
"data": {
"adjustments": [],
"base_plan": {
"external_plan_id": "example",
"id": "example",
"name": "example"
},
"base_plan_id": "example",
"created_at": "example",
"currency": "example",
"default_invoice_memo": "example",
"description": "example",
"discount": {
"amount_discount": "example",
"applies_to_price_ids": [],
"discount_type": "example",
"filters": [],
"percentage_discount": 1.0,
"reason": "example",
"tiers": [],
"trial_amount_discount": "example",
"trial_percentage_discount": 1.0,
"usage_discount": 1.0
},
"external_plan_id": "example",
"has_draft": false,
"id": "example",
"invoicing_currency": "example",
"maximum": {
"applies_to_price_ids": [],
"filters": [],
"maximum_amount": "example"
},
"maximum_amount": "example",
"metadata": {},
"minimum": {
"applies_to_price_ids": [],
"filters": [],
"minimum_amount": "example"
},
"minimum_amount": "example",
"name": "example",
"net_terms": 1,
"plan_phases": [],
"prices": [],
"product": {
"created_at": "example",
"id": "example",
"name": "example"
},
"status": "example",
"trial_config": {
"trial_period": 1,
"trial_period_unit": "example"
},
"version": 1
}
}Get subscription
This endpoint is used to fetch a Subscription given an identifier.
Inputs
- Subscription
subscription_idtextRequired - Subscription ID.
Outputs
dataobject- A subscription represents the purchase of a plan by a customer.
Example output
{
"data": {
"active_plan_phase_order": 1,
"adjustment_intervals": [],
"auto_collection": false,
"auto_issuance": false,
"billing_cycle_anchor_configuration": {
"day": 1,
"month": 1,
"year": 1
},
"billing_cycle_day": 1,
"created_at": "example",
"current_billing_period_end_date": "example",
"current_billing_period_start_date": "example",
"customer": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
},
"default_invoice_memo": "example",
"discount_intervals": [],
"end_date": "example",
"fixed_fee_quantity_schedule": [],
"id": "example",
"invoicing_threshold": "example",
"maximum_intervals": [],
"metadata": {},
"minimum_intervals": [],
"name": "example",
"net_terms": 1,
"pending_subscription_change": {
"id": "example"
},
"plan": {
"adjustments": [],
"base_plan": {},
"base_plan_id": "example",
"created_at": "example",
"currency": "example",
"default_invoice_memo": "example",
"description": "example",
"discount": {},
"external_plan_id": "example",
"has_draft": false,
"id": "example",
"invoicing_currency": "example",
"maximum": {
"applies_to_price_ids": [],
"filters": [],
"maximum_amount": "example"
},
"maximum_amount": "example",
"metadata": {},
"minimum": {
"applies_to_price_ids": [],
"filters": [],
"minimum_amount": "example"
},
"minimum_amount": "example",
"name": "example",
"net_terms": 1,
"plan_phases": [],
"prices": [],
"product": {
"created_at": "example",
"id": "example",
"name": "example"
},
"status": "example",
"trial_config": {
"trial_period": 1,
"trial_period_unit": "example"
},
"version": 1
},
"price_intervals": [],
"redeemed_coupon": {
"coupon_id": "example",
"end_date": "example",
"start_date": "example"
},
"start_date": "example",
"status": "example",
"trial_info": {
"end_date": "example"
}
}
}Get subscription usage
This endpoint is used to fetch a subscription's usage in Orb. Especially when combined with optional query parameters, this endpoint is a powerful way to build visualizations on top of Orb's event data and metrics.
Inputs
- Subscription
subscription_idtextRequired - Subscription ID.
- Granularity
granularitytext - This determines the windowing of usage reporting.One of:
day. Default:day. - Timeframe start
timeframe_startdate and time - Usage returned is inclusive of timeframe_start.
- Timeframe end
timeframe_enddate and time - Usage returned is exclusive of timeframe_end.
- Billable metric ID
billable_metric_idtext - When specified in conjunction with group_by, this parameter filters usage to a single billable metric. Note that both group_by and billable_metric_id must be specified together.
- Group by
group_bytext - Groups per-price usage by the key provided.
- View mode
view_modetext - Controls whether Orb returns cumulative usage since the start of the billing period, or incremental day-by-day usage. If your customer has minimums or discounts, it's strongly recommended that you use the default cumulative behavior.One of:
periodic,cumulative. - First dimension key
first_dimension_keytext - First Dimension Key
- First dimension value
first_dimension_valuetext - First Dimension Value
- Second dimension key
second_dimension_keytext - Second Dimension Key
- Second dimension value
second_dimension_valuetext - Second Dimension Value
Outputs
dataobject- Result.
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}Get upcoming invoice
This endpoint can be used to fetch the upcoming invoice for the current billing period given a subscription.
Inputs
- Include zero quantity line items
include_zero_quantity_line_itemstrue/false - Whether to return line items with a quantity of zero. When omitted, Orb returns every line item. A line item that is grouped as part of a line item minimum is always returned; an invoice-level minimum does not exempt it.
- Subscription
subscription_idtextRequired - Subscription Id
Outputs
dataobject- UpcomingInvoice
Example output
{
"data": {
"amount_due": "example",
"auto_collection": {
"enabled": false,
"next_attempt_at": "example",
"num_attempts": 1,
"previously_attempted_at": "example"
},
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"credit_notes": [],
"currency": "example",
"customer": {
"external_customer_id": "example",
"id": "example"
},
"customer_balance_transactions": [],
"customer_tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"discounts": [],
"due_date": "example",
"eligible_to_issue_at": "example",
"hidden_line_item_count": 1,
"hosted_invoice_url": "example",
"id": "example",
"invoice_number": "example",
"invoice_pdf": "example",
"invoice_source": "example",
"issue_failed_at": "example",
"issued_at": "example",
"line_items": [],
"maximum": {
"applies_to_price_ids": [],
"filters": [],
"maximum_amount": "example"
},
"maximum_amount": "example",
"memo": "example",
"metadata": {},
"minimum": {
"applies_to_price_ids": [],
"filters": [],
"minimum_amount": "example"
},
"minimum_amount": "example",
"paid_at": "example",
"payment_attempts": [],
"payment_failed_at": "example",
"payment_received_at": "example",
"payment_started_at": "example",
"scheduled_issue_at": "example",
"service_period_end": "example",
"service_period_start": "example",
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"status": "example",
"subscription": {
"id": "example"
},
"subtotal": "example",
"sync_failed_at": "example",
"target_date": "example",
"total": "example",
"voided_at": "example",
"will_auto_issue": false
}
}List customer credit blocks
Returns a paginated list of unexpired, non-zero credit blocks for a customer.
Inputs
- Customer
customer_idtextRequired - Customer ID.
- Limit
limitnumber - The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default:
20. - Cursor
cursortext - Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
- Currency
currencytext - The ledger currency or custom pricing unit to use.
- Include all blocks
include_all_blockstrue/false - If set to True, all expired and depleted blocks, as well as active block will be returned.Default:
false. - Effective date gte
effective_date_gtedate and time - Effective Date[Gte]
- Effective date gt
effective_date_gtdate and time - Effective Date[Gt]
- Effective date lt
effective_date_ltdate and time - Effective Date[Lt]
- Effective date lte
effective_date_ltedate and time - Effective Date[Lte]
Outputs
dataobject- CustomerCreditBalances
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}List customers
This endpoint returns a list of all customers for an account. The list of customers is ordered starting from the most recently created customer. This endpoint follows Orb's standardized pagination format.
Inputs
- Limit
limitnumber - The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default:
20. - Cursor
cursortext - Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
- Created at gte
created_at_gtedate and time - Created At[Gte]
- Created at gt
created_at_gtdate and time - Created At[Gt]
- Created at lt
created_at_ltdate and time - Created At[Lt]
- Created at lte
created_at_ltedate and time - Created At[Lte]
Outputs
dataobject- Customers
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}List invoices
This endpoint returns a list of all Invoices for an account in a list format.
Inputs
- Customer
customer_idtext - Customer Id
- External customer ID
external_customer_idtext - External Customer Id
- Subscription
subscription_idtext - Subscription Id
- Statuses
statuseslist - Status[]One or more of:
draft,issued,paid,synced,void. - Due date window
due_date_windowtext - Filters invoices by their due dates within a specific time range in the past. Specify the range as a number followed by 'd' (days) or 'm' (months). For example, '7d' filters invoices due in the last 7 days, and '2m' filters those due in the last 2 months.
- Date type
date_typetext - Date TypeOne of:
due_date(Due date),invoice_date(Invoice date). Default:invoice_date. - Due date
due_datedate - Due Date
- Due date gt
due_date_gtdate - Due Date[Gt]
- Due date lt
due_date_ltdate - Due Date[Lt]
- Amount
amounttext - Amount
- Amount gt
amount_gttext - Amount[Gt]
- Amount lt
amount_lttext - Amount[Lt]
- Is recurring
is_recurringtrue/false - Is Recurring
- Include zero quantity line items
include_zero_quantity_line_itemstrue/false - Whether to return line items with a quantity of zero. When omitted, Orb returns every line item. A line item that is grouped as part of a line item minimum is always returned; an invoice-level minimum does not exempt it.
- Limit
limitnumber - The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default:
20. - Cursor
cursortext - Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
- Invoice date gte
invoice_date_gtedate and time - Invoice Date[Gte]
- Invoice date gt
invoice_date_gtdate and time - Invoice Date[Gt]
- Invoice date lt
invoice_date_ltdate and time - Invoice Date[Lt]
- Invoice date lte
invoice_date_ltedate and time - Invoice Date[Lte]
Outputs
dataobject- Invoices
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}List plans
This endpoint returns a list of all plans for an account in a list format. The list of plans is ordered starting from the most recently created plan. The response also includes pagination_metadata which lets the caller retrieve the next page of results if they exist.
Inputs
- Limit
limitnumber - The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default:
20. - Cursor
cursortext - Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
- Status
statustext - The plan status to filter to ('active', 'archived', or 'draft').One of:
active,archived,draft. - Created at gte
created_at_gtedate and time - Created At[Gte]
- Created at gt
created_at_gtdate and time - Created At[Gt]
- Created at lt
created_at_ltdate and time - Created At[Lt]
- Created at lte
created_at_ltedate and time - Created At[Lte]
Outputs
dataobject- Plans
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}List prices
This endpoint is used to list all add-on prices created using the price creation endpoint.
Inputs
- Limit
limitnumber - The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default:
20. - Cursor
cursortext - Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
Outputs
dataobject- Prices
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}List subscriptions
This endpoint returns a list of all subscriptions for an account as a paginated list, ordered starting from the most recently created subscription. For a full discussion of the subscription resource, see Subscription.
Inputs
- Limit
limitnumber - The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default:
20. - Cursor
cursortext - Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
- Customer
customer_idtext - Customer Id
- Customer IDs
customer_idslist - Customer Id[]
- External customer ID
external_customer_idtext - External Customer Id
- External customer IDs
external_customer_idslist - External Customer Id[]
- Plan
plan_idtext - Plan Id
- External plan ID
external_plan_idtext - External Plan Id
- Statuses
statuseslist - Status[]One or more of:
active,ended,upcoming. - Created at gte
created_at_gtedate and time - Created At[Gte]
- Created at gt
created_at_gtdate and time - Created At[Gt]
- Created at lt
created_at_ltdate and time - Created At[Lt]
- Created at lte
created_at_ltedate and time - Created At[Lte]
Outputs
dataobject- Subscriptions
Example output
{
"data": {
"data": [],
"pagination_metadata": {
"has_more": false,
"next_cursor": "example"
}
}
}Send usage events
Orb's event ingestion model and API is designed around two core principles:
Inputs
- Backfill ID
backfill_idtext - If this ingestion request is part of a backfill, this parameter ties the ingested events to the backfill
- Events
eventslistRequired - Events
Outputs
dataobject- IngestionResponse
Example output
{
"data": {
"validation_failed": []
}
}Update customer
Update the customer fields you fill in. Orb keeps the other fields.
Inputs
- Customer
customer_idtextRequired - Customer ID.
- Metadata
metadataobject - User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
- Name
nametext - The full name of the customer
- Email
emailtext - A valid customer email, to be used for invoicing and notifications.
- Payment provider ID
payment_provider_idtext - The ID of this customer in an external payments solution, such as Stripe. This is used for creating charges or invoices in the external system via Orb.
- Payment provider
payment_providertext - This is used for creating charges or invoices in an external system via Orb. When not in test mode: - the connection must first be configured in the Orb webapp. - if the provider is an invoicing provider (stripe_invoice, quickbooks, bill.com, netsuite), any product mappings…One of:
quickbooks,bill.com,stripe_charge(Stripe charge),stripe_invoice(Stripe invoice),netsuite,adyen. - Shipping address
shipping_addressobject - AddressInput
- Billing address
billing_addressobject - AddressInput
- Currency
currencytext - An ISO 4217 currency string used for the customer's invoices and balance. This can only be set if the customer does not already have a currency configured. If not set at creation or update time, it will be set at subscription creation time.
- Tax ID
tax_idobject - Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
- Auto collection
auto_collectiontrue/false - Used to determine if invoices for this customer will automatically attempt to charge a saved payment method, if available. This parameter defaults to True when a payment provider is provided on customer creation.
- Auto issuance
auto_issuancetrue/false - Used to determine if invoices for this customer will be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval.If null is specified, the customer's auto issuance setting will be inherited from the account-level…
- Additional emails
additional_emailslist - Additional email addresses for this customer. If populated, these email addresses will be CC'd for customer communications. The total number of email addresses (including the primary email) cannot exceed 50.
- Email delivery
email_deliverytrue/false - Email Delivery
- Tax configuration
tax_configurationobject - Tax configuration.
- Reporting configuration
reporting_configurationobject - NewReportingConfiguration
- Accounting sync configuration
accounting_sync_configurationobject - NewAccountingSyncConfiguration
- External customer ID
external_customer_idtext - The external customer ID. This can only be set if the customer has no existing external customer ID. Since this action may change usage quantities for all existing subscriptions, it is disallowed if the customer has issued invoices with usage line items and subject to the…
- Hierarchy
hierarchyobject - The hierarchical relationships for this customer.
- Payment configuration
payment_configurationobject - Payment configuration for the customer, applicable when using Orb Invoicing with a supported payment provider such as Stripe.
- Default payment method ID
default_payment_method_idtext - The Orb ID of the payment method to set as this customer's default. Pass null to clear the customer's default payment method.
Outputs
dataobject- A customer is a buyer of your products, and the other party to the billing relationship.
Example output
{
"data": {
"accounting_sync_configuration": {
"accounting_providers": [],
"excluded": false
},
"additional_emails": [],
"auto_collection": false,
"auto_issuance": false,
"automatic_tax_enabled": false,
"balance": "example",
"billing_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"created_at": "example",
"currency": "example",
"default_payment_method": {
"created_at": "example",
"customer_id": "example",
"default": false,
"external_payment_method_id": "example",
"id": "example",
"payment_method_type": "example",
"provider_type": "example"
},
"email": "example",
"email_delivery": false,
"exempt_from_automated_tax": false,
"external_customer_id": "example",
"hierarchy": {
"children": [],
"parent": {
"external_customer_id": "example",
"id": "example"
}
},
"id": "example",
"metadata": {},
"name": "example",
"payment_configuration": {
"payment_providers": []
},
"payment_provider": "example",
"payment_provider_id": "example",
"portal_url": "example",
"reporting_configuration": {
"exempt": false
},
"shipping_address": {
"city": "example",
"country": "example",
"line1": "example",
"line2": "example",
"postal_code": "example",
"state": "example"
},
"tax_id": {
"country": "example",
"type": "example",
"value": "example"
},
"timezone": "example"
}
}