List subscriptions

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Query Parameters

limit

integer

default:20

The number of items to fetch. Defaults to 20.

Required range: 1 <= x <= 100

cursor

string | null

Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.

customer_id

string | null

customer_id[]

string[] | null

external_customer_id

string | null

external_customer_id[]

string[] | null

plan_id

string | null

external_plan_id

string | null

status

enum<string> | null

Available options:

active,

ended,

upcoming

created_at[gte]

string<date-time> | null

created_at[gt]

string<date-time> | null

created_at[lt]

string<date-time> | null

created_at[lte]

string<date-time> | null

Response

data

Subscription · object[]

required

Show child attributes

data.metadata

Metadata · object

required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

Show child attributes

data.metadata.{key}

string

data.id

string

required

data.customer

Customer · object

required

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.

Show child attributes

data.customer.metadata

Metadata · object

required

Show child attributes

data.customer.metadata.{key}

string

data.customer.id

string

required

data.customer.external_customer_id

string | null

required

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.

data.customer.name

string

required

The full name of the customer

data.customer.email

string

required

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.

data.customer.timezone

string

required

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.

data.customer.payment_provider_id

string | null

required

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.

data.customer.payment_provider

enum<string> | null

required

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.

Available options:

quickbooks,

bill.com,

stripe_charge,

stripe_invoice,

netsuite

data.customer.created_at

string<date-time>

required

data.customer.shipping_address

Address · object

required

Show child attributes

data.customer.shipping_address.line1

string | null

required

data.customer.shipping_address.line2

string | null

required

data.customer.shipping_address.city

string | null

required

data.customer.shipping_address.state

string | null

required

data.customer.shipping_address.postal_code

string | null

required

data.customer.shipping_address.country

string | null

required

data.customer.billing_address

Address · object

required

Show child attributes

data.customer.billing_address.line1

string | null

required

data.customer.billing_address.line2

string | null

required

data.customer.billing_address.city

string | null

required

data.customer.billing_address.state

string | null

required

data.customer.billing_address.postal_code

string | null

required

data.customer.billing_address.country

string | null

required

data.customer.balance

string

required

The customer's current balance in their currency.

data.customer.currency

string | null

required

data.customer.tax_id

CustomerTaxId · object

required

Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.

Supported Tax ID Countries and Types

Country	Type	Description
Albania	`al_tin`	Albania Tax Identification Number
Andorra	`ad_nrt`	Andorran NRT Number
Angola	`ao_tin`	Angola Tax Identification Number
Argentina	`ar_cuit`	Argentinian Tax ID Number
Armenia	`am_tin`	Armenia Tax Identification Number
Aruba	`aw_tin`	Aruba Tax Identification Number
Australia	`au_abn`	Australian Business Number (AU ABN)
Australia	`au_arn`	Australian Taxation Office Reference Number
Austria	`eu_vat`	European VAT Number
Azerbaijan	`az_tin`	Azerbaijan Tax Identification Number
Bahamas	`bs_tin`	Bahamas Tax Identification Number
Bahrain	`bh_vat`	Bahraini VAT Number
Bangladesh	`bd_bin`	Bangladesh Business Identification Number
Barbados	`bb_tin`	Barbados Tax Identification Number
Belarus	`by_tin`	Belarus TIN Number
Belgium	`eu_vat`	European VAT Number
Benin	`bj_ifu`	Benin Tax Identification Number (Identifiant Fiscal Unique)
Bolivia	`bo_tin`	Bolivian Tax ID
Bosnia and Herzegovina	`ba_tin`	Bosnia and Herzegovina Tax Identification Number
Brazil	`br_cnpj`	Brazilian CNPJ Number
Brazil	`br_cpf`	Brazilian CPF Number
Bulgaria	`bg_uic`	Bulgaria Unified Identification Code
Bulgaria	`eu_vat`	European VAT Number
Burkina Faso	`bf_ifu`	Burkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)
Cambodia	`kh_tin`	Cambodia Tax Identification Number
Cameroon	`cm_niu`	Cameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)
Canada	`ca_bn`	Canadian BN
Canada	`ca_gst_hst`	Canadian GST/HST Number
Canada	`ca_pst_bc`	Canadian PST Number (British Columbia)
Canada	`ca_pst_mb`	Canadian PST Number (Manitoba)
Canada	`ca_pst_sk`	Canadian PST Number (Saskatchewan)
Canada	`ca_qst`	Canadian QST Number (Québec)
Cape Verde	`cv_nif`	Cape Verde Tax Identification Number (Número de Identificação Fiscal)
Chile	`cl_tin`	Chilean TIN
China	`cn_tin`	Chinese Tax ID
Colombia	`co_nit`	Colombian NIT Number
Congo-Kinshasa	`cd_nif`	Congo (DR) Tax Identification Number (Número de Identificação Fiscal)
Costa Rica	`cr_tin`	Costa Rican Tax ID
Croatia	`eu_vat`	European VAT Number
Croatia	`hr_oib`	Croatian Personal Identification Number (OIB)
Cyprus	`eu_vat`	European VAT Number
Czech Republic	`eu_vat`	European VAT Number
Denmark	`eu_vat`	European VAT Number
Dominican Republic	`do_rcn`	Dominican RCN Number
Ecuador	`ec_ruc`	Ecuadorian RUC Number
Egypt	`eg_tin`	Egyptian Tax Identification Number
El Salvador	`sv_nit`	El Salvadorian NIT Number
Estonia	`eu_vat`	European VAT Number
Ethiopia	`et_tin`	Ethiopia Tax Identification Number
European Union	`eu_oss_vat`	European One Stop Shop VAT Number for non-Union scheme
Finland	`eu_vat`	European VAT Number
France	`eu_vat`	European VAT Number
Georgia	`ge_vat`	Georgian VAT
Germany	`de_stn`	German Tax Number (Steuernummer)
Germany	`eu_vat`	European VAT Number
Greece	`eu_vat`	European VAT Number
Guinea	`gn_nif`	Guinea Tax Identification Number (Número de Identificação Fiscal)
Hong Kong	`hk_br`	Hong Kong BR Number
Hungary	`eu_vat`	European VAT Number
Hungary	`hu_tin`	Hungary Tax Number (adószám)
Iceland	`is_vat`	Icelandic VAT
India	`in_gst`	Indian GST Number
Indonesia	`id_npwp`	Indonesian NPWP Number
Ireland	`eu_vat`	European VAT Number
Israel	`il_vat`	Israel VAT
Italy	`eu_vat`	European VAT Number
Japan	`jp_cn`	Japanese Corporate Number (Hōjin Bangō)
Japan	`jp_rn`	Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
Japan	`jp_trn`	Japanese Tax Registration Number (Tōroku Bangō)
Kazakhstan	`kz_bin`	Kazakhstani Business Identification Number
Kenya	`ke_pin`	Kenya Revenue Authority Personal Identification Number
Kyrgyzstan	`kg_tin`	Kyrgyzstan Tax Identification Number
Laos	`la_tin`	Laos Tax Identification Number
Latvia	`eu_vat`	European VAT Number
Liechtenstein	`li_uid`	Liechtensteinian UID Number
Liechtenstein	`li_vat`	Liechtenstein VAT Number
Lithuania	`eu_vat`	European VAT Number
Luxembourg	`eu_vat`	European VAT Number
Malaysia	`my_frp`	Malaysian FRP Number
Malaysia	`my_itn`	Malaysian ITN
Malaysia	`my_sst`	Malaysian SST Number
Malta	`eu_vat`	European VAT Number
Mauritania	`mr_nif`	Mauritania Tax Identification Number (Número de Identificação Fiscal)
Mexico	`mx_rfc`	Mexican RFC Number
Moldova	`md_vat`	Moldova VAT Number
Montenegro	`me_pib`	Montenegro PIB Number
Morocco	`ma_vat`	Morocco VAT Number
Nepal	`np_pan`	Nepal PAN Number
Netherlands	`eu_vat`	European VAT Number
New Zealand	`nz_gst`	New Zealand GST Number
Nigeria	`ng_tin`	Nigerian Tax Identification Number
North Macedonia	`mk_vat`	North Macedonia VAT Number
Northern Ireland	`eu_vat`	Northern Ireland VAT Number
Norway	`no_vat`	Norwegian VAT Number
Norway	`no_voec`	Norwegian VAT on e-commerce Number
Oman	`om_vat`	Omani VAT Number
Peru	`pe_ruc`	Peruvian RUC Number
Philippines	`ph_tin`	Philippines Tax Identification Number
Poland	`eu_vat`	European VAT Number
Portugal	`eu_vat`	European VAT Number
Romania	`eu_vat`	European VAT Number
Romania	`ro_tin`	Romanian Tax ID Number
Russia	`ru_inn`	Russian INN
Russia	`ru_kpp`	Russian KPP
Saudi Arabia	`sa_vat`	Saudi Arabia VAT
Senegal	`sn_ninea`	Senegal NINEA Number
Serbia	`rs_pib`	Serbian PIB Number
Singapore	`sg_gst`	Singaporean GST
Singapore	`sg_uen`	Singaporean UEN
Slovakia	`eu_vat`	European VAT Number
Slovenia	`eu_vat`	European VAT Number
Slovenia	`si_tin`	Slovenia Tax Number (davčna številka)
South Africa	`za_vat`	South African VAT Number
South Korea	`kr_brn`	Korean BRN
Spain	`es_cif`	Spanish NIF Number (previously Spanish CIF Number)
Spain	`eu_vat`	European VAT Number
Suriname	`sr_fin`	Suriname FIN Number
Sweden	`eu_vat`	European VAT Number
Switzerland	`ch_uid`	Switzerland UID Number
Switzerland	`ch_vat`	Switzerland VAT Number
Taiwan	`tw_vat`	Taiwanese VAT
Tajikistan	`tj_tin`	Tajikistan Tax Identification Number
Tanzania	`tz_vat`	Tanzania VAT Number
Thailand	`th_vat`	Thai VAT
Turkey	`tr_tin`	Turkish Tax Identification Number
Uganda	`ug_tin`	Uganda Tax Identification Number
Ukraine	`ua_vat`	Ukrainian VAT
United Arab Emirates	`ae_trn`	United Arab Emirates TRN
United Kingdom	`gb_vat`	United Kingdom VAT Number
United States	`us_ein`	United States EIN
Uruguay	`uy_ruc`	Uruguayan RUC Number
Uzbekistan	`uz_tin`	Uzbekistan TIN Number
Uzbekistan	`uz_vat`	Uzbekistan VAT Number
Venezuela	`ve_rif`	Venezuelan RIF Number
Vietnam	`vn_tin`	Vietnamese Tax ID Number
Zambia	`zm_tin`	Zambia Tax Identification Number
Zimbabwe	`zw_tin`	Zimbabwe Tax Identification Number

Show child attributes

data.customer.tax_id.country

enum<string>

required

Available options:

AD,

AE,

AL,

AM,

AO,

AR,

AT,

AU,

AW,

AZ,

BA,

BB,

BD,

BE,

BF,

BG,

BH,

BJ,

BO,

BR,

BS,

BY,

CA,

CD,

CH,

CL,

CM,

CN,

CO,

CR,

CV,

DE,

CY,

CZ,

DK,

DO,

EC,

EE,

EG,

ES,

ET,

EU,

FI,

FR,

GB,

GE,

GN,

GR,

HK,

HR,

HU,

ID,

IE,

IL,

IN,

IS,

IT,

JP,

KE,

KG,

KH,

KR,

KZ,

LA,

LI,

LT,

LU,

LV,

MA,

MD,

ME,

MK,

MR,

MT,

MX,

MY,

NG,

NL,

NO,

NP,

NZ,

OM,

PE,

PH,

PL,

PT,

RO,

RS,

RU,

SA,

SE,

SG,

SI,

SK,

SN,

SR,

SV,

TH,

TJ,

TR,

TW,

TZ,

UA,

UG,

US,

UY,

UZ,

VE,

VN,

ZA,

ZM,

ZW

data.customer.tax_id.type

enum<string>

required

Available options:

ad_nrt,

ae_trn,

al_tin,

am_tin,

ao_tin,

ar_cuit,

eu_vat,

au_abn,

au_arn,

aw_tin,

az_tin,

ba_tin,

bb_tin,

bd_bin,

bf_ifu,

bg_uic,

bh_vat,

bj_ifu,

bo_tin,

br_cnpj,

br_cpf,

bs_tin,

by_tin,

ca_bn,

ca_gst_hst,

ca_pst_bc,

ca_pst_mb,

ca_pst_sk,

ca_qst,

cd_nif,

ch_uid,

ch_vat,

cl_tin,

cm_niu,

cn_tin,

co_nit,

cr_tin,

cv_nif,

de_stn,

do_rcn,

ec_ruc,

eg_tin,

es_cif,

et_tin,

eu_oss_vat,

gb_vat,

ge_vat,

gn_nif,

hk_br,

hr_oib,

hu_tin,

id_npwp,

il_vat,

in_gst,

is_vat,

jp_cn,

jp_rn,

jp_trn,

ke_pin,

kg_tin,

kh_tin,

kr_brn,

kz_bin,

la_tin,

li_uid,

li_vat,

ma_vat,

md_vat,

me_pib,

mk_vat,

mr_nif,

mx_rfc,

my_frp,

my_itn,

my_sst,

ng_tin,

no_vat,

no_voec,

np_pan,

nz_gst,

om_vat,

pe_ruc,

ph_tin,

ro_tin,

rs_pib,

ru_inn,

ru_kpp,

sa_vat,

sg_gst,

sg_uen,

si_tin,

sn_ninea,

sr_fin,

sv_nit,

th_vat,

tj_tin,

tr_tin,

tw_vat,

tz_vat,

ua_vat,

ug_tin,

us_ein,

uy_ruc,

uz_tin,

uz_vat,

ve_rif,

vn_tin,

za_vat,

zm_tin,

zw_tin

data.customer.tax_id.value

string

required

data.customer.auto_collection

boolean

required

data.customer.exempt_from_automated_tax

boolean | null

required

data.customer.email_delivery

boolean

required

data.customer.auto_issuance

boolean | null

required

Whether invoices for this customer should be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null, inherits the account-level setting.

data.customer.additional_emails

string[]

required

data.customer.portal_url

string | null

required

data.customer.hierarchy

CustomerHierarchy · object

required

The hierarchical relationships for this customer.

Show child attributes

data.customer.hierarchy.parent

CustomerMinified · object

required

Show child attributes

data.customer.hierarchy.parent.id

string

required

data.customer.hierarchy.parent.external_customer_id

string | null

required

data.customer.hierarchy.children

CustomerMinified · object[]

required

Show child attributes

data.customer.hierarchy.children.id

string

required

data.customer.hierarchy.children.external_customer_id

string | null

required

data.customer.accounting_sync_configuration

AccountingSyncConfiguration · object

Show child attributes

data.customer.accounting_sync_configuration.excluded

boolean

required

data.customer.accounting_sync_configuration.accounting_providers

AccountingProvider · object[]

required

Show child attributes

data.customer.accounting_sync_configuration.accounting_providers.provider_type

enum<string>

required

Available options:

quickbooks,

netsuite

data.customer.accounting_sync_configuration.accounting_providers.external_provider_id

string | null

required

data.customer.reporting_configuration

ReportingConfiguration · object

Show child attributes

data.customer.reporting_configuration.exempt

boolean

required

data.customer.payment_configuration

PaymentConfiguration · object

Payment configuration for the customer, applicable when using Orb Invoicing with a supported payment provider such as Stripe.

Show child attributes

data.customer.payment_configuration.payment_providers

PaymentConfigurationItem · object[]

Provider-specific payment configuration.

Show child attributes

data.customer.payment_configuration.payment_providers.provider_type

enum<string>

required

The payment provider to configure.

Available options:

stripe

data.customer.payment_configuration.payment_providers.excluded_payment_method_types

string[]

List of Stripe payment method types to exclude for this customer. Excluded payment methods will not be available for the customer to select during payment, and will not be used for auto-collection. If a customer's default payment method becomes excluded, Orb will attempt to use the next available compatible payment method for auto-collection.

data.customer.automatic_tax_enabled

boolean | null

Whether automatic tax calculation is enabled for this customer. This field is nullable for backwards compatibility but will always return a boolean value.

data.plan

Plan · object

required

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.

Show child attributes

data.plan.metadata

Metadata · object

required

Show child attributes

data.plan.metadata.{key}

string

data.plan.id

string

required

data.plan.name

string

required

data.plan.description

string

required

data.plan.maximum_amount

string | null

required

deprecated

data.plan.minimum_amount

string | null

required

deprecated

data.plan.created_at

string<date-time>

required

data.plan.status

enum<string>

required

Available options:

active,

archived,

draft

data.plan.maximum

Maximum · object

required

deprecated

Show child attributes

data.plan.maximum.maximum_amount

string

required

Maximum amount applied

data.plan.maximum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this maximum to.

Show child attributes

data.plan.maximum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.maximum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.maximum.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.maximum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

data.plan.minimum

Minimum · object

required

deprecated

Show child attributes

data.plan.minimum.minimum_amount

string

required

Minimum amount applied

data.plan.minimum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this minimum to.

Show child attributes

data.plan.minimum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.minimum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.minimum.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.minimum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

data.plan.discount

PercentageDiscount · object

required

deprecated

PercentageDiscount
TrialDiscount
UsageDiscount
AmountDiscount

Show child attributes

data.plan.discount.discount_type

enum<string>

required

Available options:

percentage

data.plan.discount.percentage_discount

number

required

Only available if discount_type is percentage. This is a number between 0 and 1.

Required range: 0 <= x <= 1

data.plan.discount.applies_to_price_ids

string[] | null

List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

Example:

["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]

data.plan.discount.filters

PriceFilter · object[] | null

The filters that determine which prices to apply this discount to.

Show child attributes

data.plan.discount.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.discount.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.discount.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.discount.reason

string | null

data.plan.product

Product · object

required

Show child attributes

data.plan.product.created_at

string<date-time>

required

data.plan.product.id

string

required

data.plan.product.name

string

required

data.plan.version

integer

required

data.plan.trial_config

TrialConfig · object

required

Show child attributes

data.plan.trial_config.trial_period

integer | null

required

data.plan.trial_config.trial_period_unit

enum<string>

required

Available options:

days

data.plan.plan_phases

PlanPhase · object[] | null

required

Show child attributes

data.plan.plan_phases.id

string

required

data.plan.plan_phases.description

string | null

required

data.plan.plan_phases.duration

integer | null

required

How many terms of length duration_unit this phase is active for. If null, this phase is evergreen and active indefinitely

data.plan.plan_phases.duration_unit

enum<string> | null

required

Available options:

daily,

monthly,

quarterly,

semi_annual,

annual

data.plan.plan_phases.name

string

required

data.plan.plan_phases.order

integer

required

Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.

data.plan.plan_phases.minimum

Minimum · object

required

Show child attributes

data.plan.plan_phases.minimum.minimum_amount

string

required

Minimum amount applied

data.plan.plan_phases.minimum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this minimum to.

Show child attributes

data.plan.plan_phases.minimum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.plan_phases.minimum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.plan_phases.minimum.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.plan_phases.minimum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

data.plan.plan_phases.maximum

Maximum · object

required

Show child attributes

data.plan.plan_phases.maximum.maximum_amount

string

required

Maximum amount applied

data.plan.plan_phases.maximum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this maximum to.

Show child attributes

data.plan.plan_phases.maximum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.plan_phases.maximum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.plan_phases.maximum.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.plan_phases.maximum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

data.plan.plan_phases.maximum_amount

string | null

required

data.plan.plan_phases.minimum_amount

string | null

required

data.plan.plan_phases.discount

PercentageDiscount · object

required

PercentageDiscount
TrialDiscount
UsageDiscount
AmountDiscount

Show child attributes

data.plan.plan_phases.discount.discount_type

enum<string>

required

Available options:

percentage

data.plan.plan_phases.discount.percentage_discount

number

required

Only available if discount_type is percentage. This is a number between 0 and 1.

Required range: 0 <= x <= 1

data.plan.plan_phases.discount.applies_to_price_ids

string[] | null

List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

Example:

["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]

data.plan.plan_phases.discount.filters

PriceFilter · object[] | null

The filters that determine which prices to apply this discount to.

Show child attributes

data.plan.plan_phases.discount.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.plan_phases.discount.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.plan_phases.discount.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.plan_phases.discount.reason

string | null

data.plan.base_plan

PlanMinified · object

required

deprecated

Legacy field representing the parent plan if the current plan is a 'child plan', overriding prices from the parent.

Show child attributes

data.plan.base_plan.id

string | null

required

Example:

"m2t5akQeh2obwxeU"

data.plan.base_plan.external_plan_id

string | null

required

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.

Example:

"m2t5akQeh2obwxeU"

data.plan.base_plan.name

string | null

required

Example:

"Example plan"

data.plan.base_plan_id

string | null

required

deprecated

Legacy field representing the parent plan ID if the current plan is a 'child plan', overriding prices from the parent.

data.plan.external_plan_id

string | null

required

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.

data.plan.currency

string

required

deprecated

An ISO 4217 currency string or custom pricing unit (credits) for this plan's prices.

data.plan.invoicing_currency

string

required

An ISO 4217 currency string for which this plan is billed in. Matches currency unless currency is a custom pricing unit.

data.plan.net_terms

integer | null

required

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.

data.plan.default_invoice_memo

string | null

required

The default memo text on the invoices corresponding to subscriptions on this plan. Note that each subscription may configure its own memo.

data.plan.prices

required

Prices for this plan. If the plan has phases, this includes prices across all phases of the plan.

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

Show child attributes

data.plan.prices.model_type

enum<string>

required

The pricing model type

Available options:

unit

data.plan.prices.unit_config

UnitConfig · object

required

Configuration for unit pricing

Show child attributes

data.plan.prices.unit_config.unit_amount

string

required

Rate per unit of usage

data.plan.prices.unit_config.prorated

boolean

default:false

If true, subtotals from this price are prorated based on the service period

data.plan.prices.metadata

Metadata · object

required

Show child attributes

data.plan.prices.metadata.{key}

string

data.plan.prices.id

string

required

data.plan.prices.name

string

required

data.plan.prices.external_price_id

string | null

required

data.plan.prices.replaces_price_id

string | null

required

The price id this price replaces. This price will take the place of the replaced price in plan version migrations.

data.plan.prices.price_type

enum<string>

required

Available options:

usage_price,

fixed_price,

composite_price

data.plan.prices.created_at

string<date-time>

required

data.plan.prices.cadence

enum<string>

required

Available options:

one_time,

monthly,

quarterly,

semi_annual,

annual,

custom

data.plan.prices.billing_mode

enum<string>

required

Available options:

in_advance,

in_arrear

data.plan.prices.billing_cycle_configuration

BillingCycleConfiguration · object

required

Show child attributes

data.plan.prices.billing_cycle_configuration.duration

integer

required

data.plan.prices.billing_cycle_configuration.duration_unit

enum<string>

required

Available options:

day,

month

data.plan.prices.invoicing_cycle_configuration

BillingCycleConfiguration · object

required

Show child attributes

data.plan.prices.invoicing_cycle_configuration.duration

integer

required

data.plan.prices.invoicing_cycle_configuration.duration_unit

enum<string>

required

Available options:

day,

month

data.plan.prices.billable_metric

BillableMetricTiny · object

required

Show child attributes

data.plan.prices.billable_metric.id

string

required

data.plan.prices.fixed_price_quantity

number | null

required

data.plan.prices.plan_phase_order

integer | null

required

data.plan.prices.currency

string

required

data.plan.prices.conversion_rate

number | null

required

data.plan.prices.conversion_rate_config

UnitConversionRateConfig · object

required

UnitConversionRateConfig
TieredConversionRateConfig

Show child attributes

data.plan.prices.conversion_rate_config.conversion_rate_type

enum<string>

required

Available options:

unit

data.plan.prices.conversion_rate_config.unit_config

ConversionRateUnitConfig · object

required

Show child attributes

data.plan.prices.conversion_rate_config.unit_config.unit_amount

string

required

Amount per unit of overage

data.plan.prices.item

ItemSlim · object

required

A minimal representation of an Item containing only the essential identifying information.

Show child attributes

data.plan.prices.item.id

string

required

The Orb-assigned unique identifier for the item.

data.plan.prices.item.name

string

required

The name of the item.

data.plan.prices.credit_allocation

Allocation · object

required

Show child attributes

data.plan.prices.credit_allocation.currency

string

required

data.plan.prices.credit_allocation.allows_rollover

boolean

required

data.plan.prices.credit_allocation.custom_expiration

CustomExpiration · object

required

Show child attributes

data.plan.prices.credit_allocation.custom_expiration.duration

integer

required

data.plan.prices.credit_allocation.custom_expiration.duration_unit

enum<string>

required

Available options:

day,

month

data.plan.prices.credit_allocation.filters

PriceFilter · object[]

Show child attributes

data.plan.prices.credit_allocation.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.prices.credit_allocation.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.prices.credit_allocation.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.prices.composite_price_filters

PriceFilter · object[] | null

required

Show child attributes

data.plan.prices.composite_price_filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.prices.composite_price_filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.prices.composite_price_filters.values

string[]

required

The IDs or values that match this filter.

data.plan.prices.discount

PercentageDiscount · object

required

deprecated

PercentageDiscount
TrialDiscount
UsageDiscount
AmountDiscount

Show child attributes

data.plan.prices.discount.discount_type

enum<string>

required

Available options:

percentage

data.plan.prices.discount.percentage_discount

number

required

Only available if discount_type is percentage. This is a number between 0 and 1.

Required range: 0 <= x <= 1

data.plan.prices.discount.applies_to_price_ids

string[] | null

List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

Example:

["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]

data.plan.prices.discount.filters

PriceFilter · object[] | null

The filters that determine which prices to apply this discount to.

Show child attributes

data.plan.prices.discount.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.prices.discount.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.prices.discount.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.prices.discount.reason

string | null

data.plan.prices.minimum

Minimum · object

required

deprecated

Show child attributes

data.plan.prices.minimum.minimum_amount

string

required

Minimum amount applied

data.plan.prices.minimum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this minimum to.

Show child attributes

data.plan.prices.minimum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.prices.minimum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.prices.minimum.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.prices.minimum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

data.plan.prices.minimum_amount

string | null

required

deprecated

data.plan.prices.maximum

Maximum · object

required

deprecated

Show child attributes

data.plan.prices.maximum.maximum_amount

string

required

Maximum amount applied

data.plan.prices.maximum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this maximum to.

Show child attributes

data.plan.prices.maximum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.prices.maximum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.prices.maximum.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.prices.maximum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

data.plan.prices.maximum_amount

string | null

required

deprecated

data.plan.prices.dimensional_price_configuration

DimensionalPriceConfiguration · object

Show child attributes

data.plan.prices.dimensional_price_configuration.dimensional_price_group_id

string

required

data.plan.prices.dimensional_price_configuration.dimension_values

string[]

required

data.plan.adjustments

(PlanPhaseUsageDiscountAdjustment · object | PlanPhaseAmountDiscountAdjustment · object | PlanPhasePercentageDiscountAdjustment · object | PlanPhaseMinimumAdjustment · object | PlanPhaseMaximumAdjustment · object)[]

required

Adjustments for this plan. If the plan has phases, this includes adjustments across all phases of the plan.

PlanPhaseUsageDiscountAdjustment
PlanPhaseAmountDiscountAdjustment
PlanPhasePercentageDiscountAdjustment
PlanPhaseMinimumAdjustment
PlanPhaseMaximumAdjustment

Show child attributes

data.plan.adjustments.id

string

required

data.plan.adjustments.is_invoice_level

boolean

required

True for adjustments that apply to an entire invoice, false for adjustments that apply to only one price.

data.plan.adjustments.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this adjustment to.

Show child attributes

data.plan.adjustments.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.plan.adjustments.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.plan.adjustments.filters.values

string[]

required

The IDs or values that match this filter.

data.plan.adjustments.applies_to_price_ids

string[]

required

deprecated

The price IDs that this adjustment applies to.

data.plan.adjustments.reason

string | null

required

The reason for the adjustment.

data.plan.adjustments.replaces_adjustment_id

string | null

required

The adjustment id this adjustment replaces. This adjustment will take the place of the replaced adjustment in plan version migrations.

data.plan.adjustments.adjustment_type

enum<string>

required

Available options:

usage_discount

data.plan.adjustments.usage_discount

number

required

The number of usage units by which to discount the price this adjustment applies to in a given billing period.

data.plan.adjustments.plan_phase_order

integer | null

required

The plan phase in which this adjustment is active.

data.name

string

required

The name of the subscription.

data.start_date

string<date-time>

required

The date Orb starts billing for this subscription.

data.end_date

string<date-time> | null

required

The date Orb stops billing for this subscription.

data.created_at

string<date-time>

required

data.current_billing_period_start_date

string<date-time> | null

required

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.

data.current_billing_period_end_date

string<date-time> | null

required

The 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.

data.status

enum<string>

required

Available options:

active,

ended,

upcoming

data.trial_info

SubscriptionTrialInfo · object

required

Show child attributes

data.trial_info.end_date

string<date-time> | null

required

data.active_plan_phase_order

integer | null

required

The current plan phase that is active, only if the subscription's plan has phases.

data.fixed_fee_quantity_schedule

FixedFeeQuantityScheduleEntry · object[]

required

Show child attributes

data.fixed_fee_quantity_schedule.price_id

string

required

data.fixed_fee_quantity_schedule.start_date

string<date-time>

required

data.fixed_fee_quantity_schedule.end_date

string<date-time> | null

required

data.fixed_fee_quantity_schedule.quantity

number

required

data.default_invoice_memo

string | null

required

Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.

data.auto_collection

boolean | null

required

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.

data.net_terms

integer

required

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.

data.redeemed_coupon

CouponRedemption · object

required

Show child attributes

data.redeemed_coupon.coupon_id

string

required

data.redeemed_coupon.start_date

string<date-time>

required

data.redeemed_coupon.end_date

string<date-time> | null

required

data.billing_cycle_day

integer

required

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.

Required range: 1 <= x <= 31

data.billing_cycle_anchor_configuration

BillingCycleAnchorConfiguration · object

required

Show child attributes

data.billing_cycle_anchor_configuration.day

integer

required

Required range: 1 <= x <= 31

data.billing_cycle_anchor_configuration.month

integer | null

The 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).

Required range: 1 <= x <= 12

data.billing_cycle_anchor_configuration.year

integer | null

The 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.).

data.invoicing_threshold

string | null

required

data.price_intervals

PriceInterval · object[]

required

The price intervals for this subscription.

Show child attributes

data.price_intervals.id

string

required

data.price_intervals.start_date

string<date-time>

required

The start date of the price interval. This is the date that Orb starts billing for this price.

data.price_intervals.end_date

string<date-time> | null

required

The end date of the price interval. This is the date that Orb stops billing for this price.

data.price_intervals.price

UnitPrice · object

required

For more on the types of prices, see the core concepts documentation

Show child attributes

data.price_intervals.price.model_type

enum<string>

required

The pricing model type

Available options:

unit

data.price_intervals.price.unit_config

UnitConfig · object

required

Configuration for unit pricing

Show child attributes

data.price_intervals.price.unit_config.unit_amount

string

required

Rate per unit of usage

data.price_intervals.price.unit_config.prorated

boolean

default:false

If true, subtotals from this price are prorated based on the service period

data.price_intervals.price.metadata

Metadata · object

required

Show child attributes

data.price_intervals.price.metadata.{key}

string

data.price_intervals.price.id

string

required

data.price_intervals.price.name

string

required

data.price_intervals.price.external_price_id

string | null

required

data.price_intervals.price.replaces_price_id

string | null

required

The price id this price replaces. This price will take the place of the replaced price in plan version migrations.

data.price_intervals.price.price_type

enum<string>

required

Available options:

usage_price,

fixed_price,

composite_price

data.price_intervals.price.created_at

string<date-time>

required

data.price_intervals.price.cadence

enum<string>

required

Available options:

one_time,

monthly,

quarterly,

semi_annual,

annual,

custom

data.price_intervals.price.billing_mode

enum<string>

required

Available options:

in_advance,

in_arrear

data.price_intervals.price.billing_cycle_configuration

BillingCycleConfiguration · object

required

Show child attributes

data.price_intervals.price.billing_cycle_configuration.duration

integer

required

data.price_intervals.price.billing_cycle_configuration.duration_unit

enum<string>

required

Available options:

day,

month

data.price_intervals.price.invoicing_cycle_configuration

BillingCycleConfiguration · object

required

Show child attributes

data.price_intervals.price.invoicing_cycle_configuration.duration

integer

required

data.price_intervals.price.invoicing_cycle_configuration.duration_unit

enum<string>

required

Available options:

day,

month

data.price_intervals.price.billable_metric

BillableMetricTiny · object

required

Show child attributes

data.price_intervals.price.billable_metric.id

string

required

data.price_intervals.price.fixed_price_quantity

number | null

required

data.price_intervals.price.plan_phase_order

integer | null

required

data.price_intervals.price.currency

string

required

data.price_intervals.price.conversion_rate

number | null

required

data.price_intervals.price.conversion_rate_config

UnitConversionRateConfig · object

required

UnitConversionRateConfig
TieredConversionRateConfig

Show child attributes

data.price_intervals.price.conversion_rate_config.conversion_rate_type

enum<string>

required

Available options:

unit

data.price_intervals.price.conversion_rate_config.unit_config

ConversionRateUnitConfig · object

required

Show child attributes

data.price_intervals.price.conversion_rate_config.unit_config.unit_amount

string

required

Amount per unit of overage

data.price_intervals.price.item

ItemSlim · object

required

A minimal representation of an Item containing only the essential identifying information.

Show child attributes

data.price_intervals.price.item.id

string

required

The Orb-assigned unique identifier for the item.

data.price_intervals.price.item.name

string

required

The name of the item.

data.price_intervals.price.credit_allocation

Allocation · object

required

Show child attributes

data.price_intervals.price.credit_allocation.currency

string

required

data.price_intervals.price.credit_allocation.allows_rollover

boolean

required

data.price_intervals.price.credit_allocation.custom_expiration

CustomExpiration · object

required

Show child attributes

data.price_intervals.price.credit_allocation.custom_expiration.duration

integer

required

data.price_intervals.price.credit_allocation.custom_expiration.duration_unit

enum<string>

required

Available options:

day,

month

data.price_intervals.price.credit_allocation.filters

PriceFilter · object[]

Show child attributes

data.price_intervals.price.credit_allocation.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.price_intervals.price.credit_allocation.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.price_intervals.price.credit_allocation.filters.values

string[]

required

The IDs or values that match this filter.

data.price_intervals.price.composite_price_filters

PriceFilter · object[] | null

required

Show child attributes

data.price_intervals.price.composite_price_filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.price_intervals.price.composite_price_filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.price_intervals.price.composite_price_filters.values

string[]

required

The IDs or values that match this filter.

data.price_intervals.price.discount

PercentageDiscount · object

required

deprecated

PercentageDiscount
TrialDiscount
UsageDiscount
AmountDiscount

Show child attributes

data.price_intervals.price.discount.discount_type

enum<string>

required

Available options:

percentage

data.price_intervals.price.discount.percentage_discount

number

required

Only available if discount_type is percentage. This is a number between 0 and 1.

Required range: 0 <= x <= 1

data.price_intervals.price.discount.applies_to_price_ids

string[] | null

List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

Example:

["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]

data.price_intervals.price.discount.filters

PriceFilter · object[] | null

The filters that determine which prices to apply this discount to.

Show child attributes

data.price_intervals.price.discount.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.price_intervals.price.discount.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.price_intervals.price.discount.filters.values

string[]

required

The IDs or values that match this filter.

data.price_intervals.price.discount.reason

string | null

data.price_intervals.price.minimum

Minimum · object

required

deprecated

Show child attributes

data.price_intervals.price.minimum.minimum_amount

string

required

Minimum amount applied

data.price_intervals.price.minimum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this minimum to.

Show child attributes

data.price_intervals.price.minimum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.price_intervals.price.minimum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.price_intervals.price.minimum.filters.values

string[]

required

The IDs or values that match this filter.

data.price_intervals.price.minimum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

data.price_intervals.price.minimum_amount

string | null

required

deprecated

data.price_intervals.price.maximum

Maximum · object

required

deprecated

Show child attributes

data.price_intervals.price.maximum.maximum_amount

string

required

Maximum amount applied

data.price_intervals.price.maximum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this maximum to.

Show child attributes

data.price_intervals.price.maximum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.price_intervals.price.maximum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.price_intervals.price.maximum.filters.values

string[]

required

The IDs or values that match this filter.

data.price_intervals.price.maximum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

data.price_intervals.price.maximum_amount

string | null

required

deprecated

data.price_intervals.price.dimensional_price_configuration

DimensionalPriceConfiguration · object

Show child attributes

data.price_intervals.price.dimensional_price_configuration.dimensional_price_group_id

string

required

data.price_intervals.price.dimensional_price_configuration.dimension_values

string[]

required

data.price_intervals.billing_cycle_day

integer

required

The day of the month that Orb bills for this price

data.price_intervals.can_defer_billing

boolean

required

For in-arrears prices. If true, and the price interval ends mid-cycle, the final line item will be deferred to the next scheduled invoice instead of being billed mid-cycle.

data.price_intervals.fixed_fee_quantity_transitions

FixedFeeQuantityTransition · object[] | null

required

The fixed fee quantity transitions for this price interval. This is only relevant for fixed fees.

Show child attributes

data.price_intervals.fixed_fee_quantity_transitions.price_id

string

required

data.price_intervals.fixed_fee_quantity_transitions.effective_date

string<date-time>

required

data.price_intervals.fixed_fee_quantity_transitions.quantity

integer

required

data.price_intervals.current_billing_period_start_date

string<date-time> | null

required

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.

data.price_intervals.current_billing_period_end_date

string<date-time> | null

required

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.

data.price_intervals.filter

string | null

required

An additional filter to apply to usage queries.

data.price_intervals.usage_customer_ids

string[] | null

required

A list of customer IDs whose usage events will be aggregated and billed under this price interval.

data.adjustment_intervals

AdjustmentInterval · object[]

required

The adjustment intervals for this subscription sorted by the start_date of the adjustment interval.

Show child attributes

data.adjustment_intervals.id

string

required

data.adjustment_intervals.adjustment

PlanPhaseUsageDiscountAdjustment · object

required

PlanPhaseUsageDiscountAdjustment
PlanPhaseAmountDiscountAdjustment
PlanPhasePercentageDiscountAdjustment
PlanPhaseMinimumAdjustment
PlanPhaseMaximumAdjustment

Show child attributes

data.adjustment_intervals.adjustment.id

string

required

data.adjustment_intervals.adjustment.is_invoice_level

boolean

required

True for adjustments that apply to an entire invoice, false for adjustments that apply to only one price.

data.adjustment_intervals.adjustment.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this adjustment to.

Show child attributes

data.adjustment_intervals.adjustment.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.adjustment_intervals.adjustment.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.adjustment_intervals.adjustment.filters.values

string[]

required

The IDs or values that match this filter.

data.adjustment_intervals.adjustment.applies_to_price_ids

string[]

required

deprecated

The price IDs that this adjustment applies to.

data.adjustment_intervals.adjustment.reason

string | null

required

The reason for the adjustment.

data.adjustment_intervals.adjustment.replaces_adjustment_id

string | null

required

The adjustment id this adjustment replaces. This adjustment will take the place of the replaced adjustment in plan version migrations.

data.adjustment_intervals.adjustment.adjustment_type

enum<string>

required

Available options:

usage_discount

data.adjustment_intervals.adjustment.usage_discount

number

required

The number of usage units by which to discount the price this adjustment applies to in a given billing period.

data.adjustment_intervals.adjustment.plan_phase_order

integer | null

required

The plan phase in which this adjustment is active.

data.adjustment_intervals.start_date

string<date-time>

required

The start date of the adjustment interval.

data.adjustment_intervals.end_date

string<date-time> | null

required

The end date of the adjustment interval.

data.adjustment_intervals.applies_to_price_interval_ids

string[]

required

The price interval IDs that this adjustment applies to.

data.discount_intervals

(AmountDiscountInterval · object | PercentageDiscountInterval · object | UsageDiscountInterval · object)[]

required

deprecated

The discount intervals for this subscription sorted by the start_date. This field is deprecated in favor of adjustment_intervals.

AmountDiscountInterval
PercentageDiscountInterval
UsageDiscountInterval

Show child attributes

data.discount_intervals.discount_type

enum<string>

required

Available options:

amount

data.discount_intervals.amount_discount

string

required

Only available if discount_type is amount.

data.discount_intervals.start_date

string<date-time>

required

The start date of the discount interval.

data.discount_intervals.end_date

string<date-time> | null

required

The end date of the discount interval.

data.discount_intervals.filters

PriceFilter · object[]

required

The filters that determine which prices this discount interval applies to.

Show child attributes

data.discount_intervals.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.discount_intervals.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.discount_intervals.filters.values

string[]

required

The IDs or values that match this filter.

data.discount_intervals.applies_to_price_interval_ids

string[]

required

The price interval ids that this discount interval applies to.

data.minimum_intervals

MinimumInterval · object[]

required

deprecated

The minimum intervals for this subscription sorted by the start_date. This field is deprecated in favor of adjustment_intervals.

Show child attributes

data.minimum_intervals.start_date

string<date-time>

required

The start date of the minimum interval.

data.minimum_intervals.end_date

string<date-time> | null

required

The end date of the minimum interval.

data.minimum_intervals.filters

PriceFilter · object[]

required

The filters that determine which prices this minimum interval applies to.

Show child attributes

data.minimum_intervals.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.minimum_intervals.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.minimum_intervals.filters.values

string[]

required

The IDs or values that match this filter.

data.minimum_intervals.applies_to_price_interval_ids

string[]

required

The price interval ids that this minimum interval applies to.

data.minimum_intervals.minimum_amount

string

required

The minimum amount to charge in a given billing period for the price intervals this minimum applies to.

data.maximum_intervals

MaximumInterval · object[]

required

deprecated

The maximum intervals for this subscription sorted by the start_date. This field is deprecated in favor of adjustment_intervals.

Show child attributes

data.maximum_intervals.start_date

string<date-time>

required

The start date of the maximum interval.

data.maximum_intervals.end_date

string<date-time> | null

required

The end date of the maximum interval.

data.maximum_intervals.filters

PriceFilter · object[]

required

The filters that determine which prices this maximum interval applies to.

Show child attributes

data.maximum_intervals.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

data.maximum_intervals.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

data.maximum_intervals.filters.values

string[]

required

The IDs or values that match this filter.

data.maximum_intervals.applies_to_price_interval_ids

string[]

required

The price interval ids that this maximum interval applies to.

data.maximum_intervals.maximum_amount

string

required

The maximum amount to charge in a given billing period for the price intervals this transform applies to.

data.pending_subscription_change

SubscriptionChangeMinified · object

required

A pending subscription change if one exists on this subscription.

Show child attributes

data.pending_subscription_change.id

string

required

pagination_metadata

PaginationMetadata · object

required

Show child attributes

pagination_metadata.has_more

boolean

required

pagination_metadata.next_cursor

string | null

required

API documentation

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

List subscriptions

Authorizations

Query Parameters

Response

Supported Tax ID Countries and Types