Orb

App · 20 actions

Manage customers, subscriptions, invoices and usage events in Orb.

Actions

ActionWhat it does
Cancel subscriptionThis endpoint can be used to cancel an existing subscription.
Check connectionThis 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 customerThis operation is used to create an Orb customer, who is party to the core billing relationship.
Create subscriptionA subscription represents the purchase of a plan by a customer.
Delete customerThis performs a deletion of this customer, its subscriptions, and its invoices, provided the customer does not have any issued invoices.
Get customerThis endpoint is used to fetch customer details given an identifier.
Get customer by external IDThis endpoint is used to fetch customer details given an external_customer_id (see Customer ID Aliases).
Get invoiceThis endpoint is used to fetch an Invoice given an identifier.
Get planThis endpoint is used to fetch plan details given a plan identifier.
Get subscriptionThis endpoint is used to fetch a Subscription given an identifier.
Get subscription usageThis endpoint is used to fetch a subscription's usage in Orb.
Get upcoming invoiceThis endpoint can be used to fetch the upcoming invoice for the current billing period given a subscription.
List customer credit blocksReturns a paginated list of unexpired, non-zero credit blocks for a customer.
List customersThis endpoint returns a list of all customers for an account.
List invoicesThis endpoint returns a list of all Invoices for an account in a list format.
List plansThis endpoint returns a list of all plans for an account in a list format.
List pricesThis endpoint is used to list all add-on prices created using the price creation endpoint.
List subscriptionsThis endpoint returns a list of all subscriptions for an account as a paginated list, ordered starting from the most recently created subscription.
Send usage eventsOrb's event ingestion model and API is designed around two core principles:
Update customerUpdate 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

Subscriptionsubscription_idtextRequired
Subscription ID.
Cancel optioncancel_optiontextRequired
Determines the timing of subscription cancellationOne of: end_of_subscription_term (End of subscription term), immediate, requested_date (Requested date).
Cancellation datecancellation_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 voidallow_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

Metadatametadataobject
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.
NamenametextRequired
The full name of the customer
EmailemailtextRequired
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.
Timezonetimezonetext
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 IDexternal_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 IDpayment_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 providerpayment_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 addressshipping_addressobject
AddressInput
Billing addressbilling_addressobject
AddressInput
Currencycurrencytext
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 IDtax_idobject
Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
Auto collectionauto_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 issuanceauto_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 deliveryemail_deliverytrue/false
Email Delivery
Tax configurationtax_configurationobject
Tax configuration.
Reporting configurationreporting_configurationobject
NewReportingConfiguration
Accounting sync configurationaccounting_sync_configurationobject
NewAccountingSyncConfiguration
Additional emailsadditional_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.
Hierarchyhierarchyobject
The hierarchical relationships for this customer.
Payment configurationpayment_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 IDSusage_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…
Filterfiltertext
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.
Metadatametadataobject
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.
Planplan_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 IDexternal_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 overridesprice_overrideslist
Optionally provide a list of overrides for prices on the plan
Per credit overage amountper_credit_overage_amountnumber
Per Credit Overage Amount
Credits overage ratecredits_overage_ratenumber
Credits Overage Rate
Trial duration daystrial_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 termsnet_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 collectionauto_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 issuanceauto_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 memodefault_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 codecoupon_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 thresholdinvoicing_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 orderinitial_phase_ordernumber
The phase of the plan to start with
Add pricesadd_priceslist
Additional prices to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
Remove pricesremove_priceslist
Plan prices to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
Replace pricesreplace_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 adjustmentsadd_adjustmentslist
Additional adjustments to be added to the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
Remove adjustmentsremove_adjustmentslist
Plan adjustments to be removed from the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
Replace adjustmentsreplace_adjustmentslist
Plan adjustments to be replaced with additional adjustments on the subscription. (Only available for accounts that have migrated off of legacy subscription overrides)
Customercustomer_idtext
Customer Id
External customer IDexternal_customer_idtext
External Customer Id
Currencycurrencytext
The currency to use for the subscription. If not specified, the invoicing currency for the plan will be used.
Namenametext
The name to use for the subscription. If not specified, the plan name will be used.
Start datestart_datedate and time
Start Date
End dateend_datedate and time
End Date
Plan version numberplan_version_numbernumber
Specifies which version of the plan to subscribe to. If null, the default version will be used.
External marketplaceexternal_marketplacetext
External MarketplaceOne of: google, aws, azure.
External marketplace reporting IDexternal_marketplace_reporting_idtext
External Marketplace Reporting Id
Aws regionaws_regiontext
Aws Region
Align billing with subscription start datealign_billing_with_subscription_start_datetrue/false
Align Billing With Subscription Start DateDefault: false.
Billing cycle anchor configurationbilling_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

Customercustomer_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

Customercustomer_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 IDexternal_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

Invoiceinvoice_idtextRequired
Invoice ID.
Include zero quantity line itemsinclude_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

Planplan_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

Subscriptionsubscription_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

Subscriptionsubscription_idtextRequired
Subscription ID.
Granularitygranularitytext
This determines the windowing of usage reporting.One of: day. Default: day.
Timeframe starttimeframe_startdate and time
Usage returned is inclusive of timeframe_start.
Timeframe endtimeframe_enddate and time
Usage returned is exclusive of timeframe_end.
Billable metric IDbillable_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 bygroup_bytext
Groups per-price usage by the key provided.
View modeview_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 keyfirst_dimension_keytext
First Dimension Key
First dimension valuefirst_dimension_valuetext
First Dimension Value
Second dimension keysecond_dimension_keytext
Second Dimension Key
Second dimension valuesecond_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 itemsinclude_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.
Subscriptionsubscription_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

Customercustomer_idtextRequired
Customer ID.
Limitlimitnumber
The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default: 20.
Cursorcursortext
Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
Currencycurrencytext
The ledger currency or custom pricing unit to use.
Include all blocksinclude_all_blockstrue/false
If set to True, all expired and depleted blocks, as well as active block will be returned.Default: false.
Effective date gteeffective_date_gtedate and time
Effective Date[Gte]
Effective date gteffective_date_gtdate and time
Effective Date[Gt]
Effective date lteffective_date_ltdate and time
Effective Date[Lt]
Effective date lteeffective_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

Limitlimitnumber
The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default: 20.
Cursorcursortext
Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
Created at gtecreated_at_gtedate and time
Created At[Gte]
Created at gtcreated_at_gtdate and time
Created At[Gt]
Created at ltcreated_at_ltdate and time
Created At[Lt]
Created at ltecreated_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

Customercustomer_idtext
Customer Id
External customer IDexternal_customer_idtext
External Customer Id
Subscriptionsubscription_idtext
Subscription Id
Statusesstatuseslist
Status[]One or more of: draft, issued, paid, synced, void.
Due date windowdue_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 typedate_typetext
Date TypeOne of: due_date (Due date), invoice_date (Invoice date). Default: invoice_date.
Due datedue_datedate
Due Date
Due date gtdue_date_gtdate
Due Date[Gt]
Due date ltdue_date_ltdate
Due Date[Lt]
Amountamounttext
Amount
Amount gtamount_gttext
Amount[Gt]
Amount ltamount_lttext
Amount[Lt]
Is recurringis_recurringtrue/false
Is Recurring
Include zero quantity line itemsinclude_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.
Limitlimitnumber
The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default: 20.
Cursorcursortext
Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
Invoice date gteinvoice_date_gtedate and time
Invoice Date[Gte]
Invoice date gtinvoice_date_gtdate and time
Invoice Date[Gt]
Invoice date ltinvoice_date_ltdate and time
Invoice Date[Lt]
Invoice date lteinvoice_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

Limitlimitnumber
The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default: 20.
Cursorcursortext
Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
Statusstatustext
The plan status to filter to ('active', 'archived', or 'draft').One of: active, archived, draft.
Created at gtecreated_at_gtedate and time
Created At[Gte]
Created at gtcreated_at_gtdate and time
Created At[Gt]
Created at ltcreated_at_ltdate and time
Created At[Lt]
Created at ltecreated_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

Limitlimitnumber
The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default: 20.
Cursorcursortext
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

Limitlimitnumber
The number of items to fetch. Defaults to 20.From 1.0 to 100.0. Default: 20.
Cursorcursortext
Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.
Customercustomer_idtext
Customer Id
Customer IDscustomer_idslist
Customer Id[]
External customer IDexternal_customer_idtext
External Customer Id
External customer IDsexternal_customer_idslist
External Customer Id[]
Planplan_idtext
Plan Id
External plan IDexternal_plan_idtext
External Plan Id
Statusesstatuseslist
Status[]One or more of: active, ended, upcoming.
Created at gtecreated_at_gtedate and time
Created At[Gte]
Created at gtcreated_at_gtdate and time
Created At[Gt]
Created at ltcreated_at_ltdate and time
Created At[Lt]
Created at ltecreated_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 IDbackfill_idtext
If this ingestion request is part of a backfill, this parameter ties the ingested events to the backfill
EventseventslistRequired
Events

Outputs

dataobject
IngestionResponse
Example output
{
  "data": {
    "validation_failed": []
  }
}

Update customer

Update the customer fields you fill in. Orb keeps the other fields.

Inputs

Customercustomer_idtextRequired
Customer ID.
Metadatametadataobject
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.
Namenametext
The full name of the customer
Emailemailtext
A valid customer email, to be used for invoicing and notifications.
Payment provider IDpayment_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 providerpayment_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 addressshipping_addressobject
AddressInput
Billing addressbilling_addressobject
AddressInput
Currencycurrencytext
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 IDtax_idobject
Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
Auto collectionauto_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 issuanceauto_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 emailsadditional_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 deliveryemail_deliverytrue/false
Email Delivery
Tax configurationtax_configurationobject
Tax configuration.
Reporting configurationreporting_configurationobject
NewReportingConfiguration
Accounting sync configurationaccounting_sync_configurationobject
NewAccountingSyncConfiguration
External customer IDexternal_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…
Hierarchyhierarchyobject
The hierarchical relationships for this customer.
Payment configurationpayment_configurationobject
Payment configuration for the customer, applicable when using Orb Invoicing with a supported payment provider such as Stripe.
Default payment method IDdefault_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"
  }
}

On this page