API Documentation
Alert
Customer
Credit
- GETFetch customer credit balance by external customer id
- GETFetch customer credits ledger by external ID
- POSTCreate ledger entry by external ID
- GETList top-ups by external ID
- POSTCreate top-up by external ID
- DELDelete top-up by external ID
- GETFetch customer credit balance
- GETFetch customer credits ledger
- POSTCreate ledger entry
- GETList top-ups
- POSTCreate top-up
- DELDelete top-up
Dimensional Price Group
Event
Invoice
Availability
Plan
Price
Subscription
- GETList subscriptions
- POSTCreate subscription
- GETFetch subscription
- PUTUpdate subscription
- POSTCancel subscription
- GETFetch subscription costs
- GETFetch subscription schedule
- POSTSchedule plan change
- POSTTrigger phase
- POSTUnschedule subscription cancellation
- POSTUnschedule fixed fee quantity updates
- POSTUnschedule plan change
- POSTUpdate price quantity
- POSTUpdate trial for subscription
- GETFetch subscription usage
Price interval
Fetch subscription
This endpoint is used to fetch a Subscription given an identifier.
Authorizations
API Keys can be issued in the Orb's web application.
Path Parameters
Response
A subscription represents the purchase of a plan by a customer.
By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition.
Subscriptions also default to beginning of month alignment, which means the first invoice issued for the
subscription will have pro-rated charges between the start_date and the first of the following month. Subsequent
billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing).
Depending on the plan configuration, any flat recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to in-advance billing. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period.
The current plan phase that is active, only if the subscription's plan has phases.
The adjustment intervals for this subscription.
amount_discount The amount by which to discount the prices this adjustment applies to in a given billing period.
The price IDs that this adjustment applies to.
True for adjustments that apply to an entire invocice, false for adjustments that apply to only one price.
The plan phase in which this adjustment is active.
The reason for the adjustment.
The price interval IDs that this adjustment applies to.
The end date of the adjustment interval.
The start date of the adjustment interval.
Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. This property defaults to the plan's behavior. If null, defaults to the customer's setting.
The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.
1 < x < 31The month on which the billing cycle is anchored (e.g. a quarterly price anchored in February would have cycles starting February, May, August, and November).
1 < x < 12The year on which the billing cycle is anchored (e.g. a 2 year billing cycle anchored on 2021 would have cycles starting on 2021, 2023, 2025, etc.).
The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.
1 < x < 31The end of the current billing period. This is an exclusive timestamp, such that the instant returned is not part of the billing period. Set to null for subscriptions that are not currently active.
The start date of the current billing period. This is an inclusive timestamp; the instant returned is exactly the beginning of the billing period. Set to null if the subscription is not currently active.
A customer is a buyer of your products, and the other party to the billing relationship.
In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these
match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an
external_customer_id with your own identifier. See
Customer ID Aliases for further information about how these
aliases work in Orb.
In addition to having an identifier in your system, a customer may exist in a payment provider solution like
Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.
A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.
The customer's current balance in their currency.
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.
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.
User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
The full name of the customer
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.
quickbooks, bill.com, stripe_charge, stripe_invoice, netsuite 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.
Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.
Supported Tax ID Countries and Types
| Country | Type | Description |
|----------------|--------------|---------------------------------------------|
| Andorra | ad_nrt | Andorran NRT Number |
| Argentina | ar_cuit | Argentinian Tax ID Number |
| Australia | au_abn | Australian Business Number (AU ABN) |
| Australia | au_arn | Australian Taxation Office Reference Number |
| Austria | eu_vat | European VAT Number |
| Bahrain | bh_vat | Bahraini VAT Number |
| Belgium | eu_vat | European VAT Number |
| Bolivia | bo_tin | Bolivian Tax ID |
| Brazil | br_cnpj | Brazilian CNPJ Number |
| Brazil | br_cpf | Brazilian CPF Number |
| Bulgaria | bg_uic | Bulgaria Unified Identification Code |
| Bulgaria | eu_vat | European VAT Number |
| Canada | ca_bn | Canadian BN |
| Canada | ca_gst_hst | Canadian GST/HST Number |
| Canada | ca_pst_bc | Canadian PST Number (British Columbia) |
| Canada | ca_pst_mb | Canadian PST Number (Manitoba) |
| Canada | ca_pst_sk | Canadian PST Number (Saskatchewan) |
| Canada | ca_qst | Canadian QST Number (Québec) |
| Chile | cl_tin | Chilean TIN |
| China | cn_tin | Chinese Tax ID |
| Colombia | co_nit | Colombian NIT Number |
| Costa Rica | cr_tin | Costa Rican Tax ID |
| Croatia | eu_vat | European VAT Number |
| Cyprus | eu_vat | European VAT Number |
| Czech Republic | eu_vat | European VAT Number |
| Denmark | eu_vat | European VAT Number |
| Dominican Republic | do_rcn | Dominican RCN Number |
| Ecuador | ec_ruc | Ecuadorian RUC Number |
| Egypt | eg_tin | Egyptian Tax Identification Number |
| El Salvador | sv_nit | El Salvadorian NIT Number |
| Estonia | eu_vat | European VAT Number |
| EU | eu_oss_vat | European One Stop Shop VAT Number for non-Union scheme |
| Finland | eu_vat | European VAT Number |
| France | eu_vat | European VAT Number |
| Georgia | ge_vat | Georgian VAT |
| Germany | eu_vat | European VAT Number |
| Greece | eu_vat | European VAT Number |
| Hong Kong | hk_br | Hong Kong BR Number |
| Hungary | eu_vat | European VAT Number |
| Hungary | hu_tin | Hungary Tax Number (adószám) |
| Iceland | is_vat | Icelandic VAT |
| India | in_gst | Indian GST Number |
| Indonesia | id_npwp | Indonesian NPWP Number |
| Ireland | eu_vat | European VAT Number |
| Israel | il_vat | Israel VAT |
| Italy | eu_vat | European VAT Number |
| Japan | jp_cn | Japanese Corporate Number (Hōjin Bangō) |
| Japan | jp_rn | Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō) |
| Japan | jp_trn | Japanese Tax Registration Number (Tōroku Bangō) |
| Kazakhstan | kz_bin | Kazakhstani Business Identification Number |
| Kenya | ke_pin | Kenya Revenue Authority Personal Identification Number |
| Latvia | eu_vat | European VAT Number |
| Liechtenstein | li_uid | Liechtensteinian UID Number |
| Lithuania | eu_vat | European VAT Number |
| Luxembourg | eu_vat | European VAT Number |
| Malaysia | my_frp | Malaysian FRP Number |
| Malaysia | my_itn | Malaysian ITN |
| Malaysia | my_sst | Malaysian SST Number |
| Malta | eu_vat | European VAT Number |
| Mexico | mx_rfc | Mexican RFC Number |
| Netherlands | eu_vat | European VAT Number |
| New Zealand | nz_gst | New Zealand GST Number |
| Nigeria | ng_tin | Nigerian Tax Identification Number |
| Norway | no_vat | Norwegian VAT Number |
| Norway | no_voec | Norwegian VAT on e-commerce Number |
| Oman | om_vat | Omani VAT Number |
| Peru | pe_ruc | Peruvian RUC Number |
| Philippines | ph_tin | Philippines Tax Identification Number |
| Poland | eu_vat | European VAT Number |
| Portugal | eu_vat | European VAT Number |
| Romania | eu_vat | European VAT Number |
| Romania | ro_tin | Romanian Tax ID Number |
| Russia | ru_inn | Russian INN |
| Russia | ru_kpp | Russian KPP |
| Saudi Arabia | sa_vat | Saudi Arabia VAT |
| Serbia | rs_pib | Serbian PIB Number |
| Singapore | sg_gst | Singaporean GST |
| Singapore | sg_uen | Singaporean UEN |
| Slovakia | eu_vat | European VAT Number |
| Slovenia | eu_vat | European VAT Number |
| Slovenia | si_tin | Slovenia Tax Number (davčna številka) |
| South Africa | za_vat | South African VAT Number |
| South Korea | kr_brn | Korean BRN |
| Spain | es_cif | Spanish NIF Number (previously Spanish CIF Number) |
| Spain | eu_vat | European VAT Number |
| Sweden | eu_vat | European VAT Number |
| Switzerland | ch_vat | Switzerland VAT Number |
| Taiwan | tw_vat | Taiwanese VAT |
| Thailand | th_vat | Thai VAT |
| Turkey | tr_tin | Turkish Tax Identification Number |
| Ukraine | ua_vat | Ukrainian VAT |
| United Arab Emirates | ae_trn | United Arab Emirates TRN |
| United Kingdom | eu_vat | Northern Ireland VAT Number |
| United Kingdom | gb_vat | United Kingdom VAT Number |
| United States | us_ein | United States EIN |
| Uruguay | uy_ruc | Uruguayan RUC Number |
| Venezuela | ve_rif | Venezuelan RIF Number |
| Vietnam | vn_tin | Vietnamese Tax ID Number |
AD, AE, AR, AT, AU, BE, BG, BH, BO, BR, CA, CH, CL, CN, CO, CR, CY, CZ, DE, DK, EE, DO, EC, EG, ES, EU, FI, FR, GB, GE, GR, HK, HR, HU, ID, IE, IL, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MT, MX, MY, NG, NL, NO, NZ, OM, PE, PH, PL, PT, RO, RS, RU, SA, SE, SG, SI, SK, SV, TH, TR, TW, UA, US, UY, VE, VN, ZA ad_nrt, ae_trn, ar_cuit, eu_vat, au_abn, au_arn, bg_uic, bh_vat, bo_tin, br_cnpj, br_cpf, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, ch_vat, cl_tin, cn_tin, co_nit, cr_tin, do_rcn, ec_ruc, eg_tin, es_cif, eu_oss_vat, gb_vat, ge_vat, hk_br, hu_tin, id_npwp, il_vat, in_gst, is_vat, jp_cn, jp_rn, jp_trn, ke_pin, kr_brn, kz_bin, li_uid, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, nz_gst, om_vat, pe_ruc, ph_tin, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sv_nit, th_vat, tr_tin, tw_vat, ua_vat, us_ein, uy_ruc, ve_rif, vn_tin, za_vat 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.
Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.
The discount intervals for this subscription.
Only available if discount_type is amount.
The price ids that this discount interval applies to.
The price interval ids that this discount interval applies to.
amount The end date of the discount interval.
The start date of the discount interval.
The date Orb stops billing for this subscription.
The maximum intervals for this subscription.
The price ids that this maximum interval applies to.
The price interval ids that this maximum interval applies to.
The end date of the maximum interval.
The maximum amount to charge in a given billing period for the price intervals this transform applies to.
The start date of the maximum interval.
User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
The minimum intervals for this subscription.
The price ids that this minimum interval applies to.
The price interval ids that this minimum interval applies to.
The end date of the minimum interval.
The minimum amount to charge in a given billing period for the price intervals this minimum applies to.
The start date of the minimum interval.
Determines the difference between the invoice issue date for subscription invoices as the date that they are due. A value of 0 here represents that the invoice is due on issue, whereas a value of 30 represents that the customer has a month to pay the invoice.
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.
Adjustments for this plan. If the plan has phases, this includes adjustments across all phases of the plan.
amount_discount The amount by which to discount the prices this adjustment applies to in a given billing period.
The price IDs that this adjustment applies to.
True for adjustments that apply to an entire invocice, false for adjustments that apply to only one price.
The plan phase in which this adjustment is active.
The reason for the adjustment.
An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.
The parent plan id if the given plan was created by overriding one or more of the parent's prices
An ISO 4217 currency string or custom pricing unit (credits) for this plan's prices.
The default memo text on the invoices corresponding to subscriptions on this plan. Note that each subscription may configure its own memo.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 < x < 1An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.
An ISO 4217 currency string for which this plan is billed in. Matches currency unless currency is a custom pricing unit.
User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
Determines the difference between the invoice issue date and the due date. A value of "0" here signifies that invoices are due on issue, whereas a value of "30" means that the customer has a month to pay the invoice before its overdue. Note that individual subscriptions or invoices may set a different net terms configuration.
List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 < x < 1How many terms of length duration_unit this phase is active for. If null, this phase is evergreen and active indefinitely
daily, monthly, quarterly, semi_annual, annual Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.
Prices for this plan. If the plan has phases, this includes prices across all phases of the plan.
one_time, monthly, quarterly, semi_annual, annual, custom List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 < x < 1User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
unit usage_price, fixed_price active, archived, draft The price intervals for this subscription.
The day of the month that Orb bills for this price
The end of the current billing period. This is an exclusive timestamp, such that the instant returned is exactly the end of the billing period. Set to null if this price interval is not currently active.
The start date of the current billing period. This is an inclusive timestamp; the instant returned is exactly the beginning of the billing period. Set to null if this price interval is not currently active.
The end date of the price interval. This is the date that Orb stops billing for this price.
The fixed fee quantity transitions for this price interval. This is only relevant for fixed fees.
The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.
Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.
For more on the types of prices, see the core concepts documentation
one_time, monthly, quarterly, semi_annual, annual, custom List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
percentage Only available if discount_type is percentage. This is a number between 0 and 1.
0 < x < 1User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.
unit usage_price, fixed_price The start date of the price interval. This is the date that Orb starts billing for this price.
The date Orb starts billing for this subscription.
active, ended, upcoming Was this page helpful?