orb-billing
Version:
The official TypeScript library for the Orb API
1,034 lines (920 loc) • 120 kB
text/typescript
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
import { APIResource } from '../core/resource';
import * as Shared from './shared';
import { InvoicesPage } from './shared';
import { APIPromise } from '../core/api-promise';
import { Page, type PageParams, PagePromise } from '../core/pagination';
import { buildHeaders } from '../internal/headers';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';
/**
* An [`Invoice`](/core-concepts#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 at the end of a billing period, or as
* the result of an action, such as a cancellation.
*/
export class Invoices extends APIResource {
/**
* This endpoint is used to create a one-off invoice for a customer.
*
* @example
* ```ts
* const invoice = await client.invoices.create({
* currency: 'USD',
* invoice_date: '2019-12-27T18:11:19.117Z',
* line_items: [
* {
* end_date: '2023-09-22',
* item_id: '4khy3nwzktxv7',
* model_type: 'unit',
* name: 'Line Item Name',
* quantity: 1,
* start_date: '2023-09-22',
* unit_config: { unit_amount: 'unit_amount' },
* },
* ],
* });
* ```
*/
create(body: InvoiceCreateParams, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.post('/invoices', { body, ...options });
}
/**
* This endpoint allows you to update the `metadata`, `net_terms`, `due_date`,
* `invoice_date`, and `auto_collection` properties on an invoice. If you pass null
* for the metadata value, it will clear any existing metadata for that invoice.
*
* `metadata` can be modified regardless of invoice state. `net_terms`, `due_date`,
* `invoice_date`, and `auto_collection` can only be modified if the invoice is in
* a `draft` state. `invoice_date` can only be modified for non-subscription
* invoices.
*
* @example
* ```ts
* const invoice = await client.invoices.update('invoice_id');
* ```
*/
update(invoiceID: string, body: InvoiceUpdateParams, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.put(path`/invoices/${invoiceID}`, { body, ...options });
}
/**
* This endpoint returns a list of all [`Invoice`](/core-concepts#invoice)s for an
* account in a list format.
*
* The list of invoices is ordered starting from the most recently issued invoice
* date. The response also includes
* [`pagination_metadata`](/api-reference/pagination), which lets the caller
* retrieve the next page of results if they exist.
*
* By default, this only returns invoices that are `issued`, `paid`, or `synced`.
*
* When fetching any `draft` invoices, this returns the last-computed invoice
* values for each draft invoice, which may not always be up-to-date since Orb
* regularly refreshes invoices asynchronously.
*
* If you don't need line item details, minimums, maximums, or discounts, prefer
* the [list invoices summary](/api-reference/invoice/list-invoices-summary)
* endpoint for better performance.
*
* @example
* ```ts
* // Automatically fetches more pages as needed.
* for await (const invoice of client.invoices.list()) {
* // ...
* }
* ```
*/
list(
query: InvoiceListParams | null | undefined = {},
options?: RequestOptions,
): PagePromise<InvoicesPage, Shared.Invoice> {
return this._client.getAPIList('/invoices', Page<Shared.Invoice>, { query, ...options });
}
/**
* This endpoint deletes an invoice line item from a draft invoice.
*
* This endpoint only allows deletion of one-off line items (not subscription-based
* line items). The invoice must be in a draft status for this operation to
* succeed.
*
* @example
* ```ts
* await client.invoices.deleteLineItem('line_item_id', {
* invoice_id: 'invoice_id',
* });
* ```
*/
deleteLineItem(
lineItemID: string,
params: InvoiceDeleteLineItemParams,
options?: RequestOptions,
): APIPromise<void> {
const { invoice_id } = params;
return this._client.delete(path`/invoices/${invoice_id}/invoice_line_items/${lineItemID}`, {
...options,
headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
});
}
/**
* This endpoint is used to fetch an [`Invoice`](/core-concepts#invoice) given an
* identifier.
*
* @example
* ```ts
* const invoice = await client.invoices.fetch('invoice_id');
* ```
*/
fetch(invoiceID: string, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.get(path`/invoices/${invoiceID}`, options);
}
/**
* This endpoint can be used to fetch the upcoming
* [invoice](/core-concepts#invoice) for the current billing period given a
* subscription.
*
* @example
* ```ts
* const response = await client.invoices.fetchUpcoming({
* subscription_id: 'subscription_id',
* });
* ```
*/
fetchUpcoming(
query: InvoiceFetchUpcomingParams,
options?: RequestOptions,
): APIPromise<InvoiceFetchUpcomingResponse> {
return this._client.get('/invoices/upcoming', { query, ...options });
}
/**
* This endpoint allows an eligible invoice to be issued manually. This is only
* possible with invoices where status is `draft`, `will_auto_issue` is false, and
* an `eligible_to_issue_at` is a time in the past. Issuing an invoice could
* possibly trigger side effects, some of which could be customer-visible (e.g.
* sending emails, auto-collecting payment, syncing the invoice to external
* providers, etc).
*
* @example
* ```ts
* const invoice = await client.invoices.issue('invoice_id');
* ```
*/
issue(
invoiceID: string,
body: InvoiceIssueParams | null | undefined = {},
options?: RequestOptions,
): APIPromise<Shared.Invoice> {
return this._client.post(path`/invoices/${invoiceID}/issue`, { body, ...options });
}
/**
* This endpoint allows an eligible invoice to be issued manually. This is only
* possible with invoices where status is `draft`, `will_auto_issue` is false, and
* an `eligible_to_issue_at` is a time in the past. Issuing an invoice could
* possibly trigger side effects, some of which could be customer-visible (e.g.
* sending emails, auto-collecting payment, syncing the invoice to external
* providers, etc).
*
* This is a lighter-weight alternative to the issue invoice endpoint, returning an
* invoice summary without any line item details.
*
* @example
* ```ts
* const response = await client.invoices.issueSummary(
* 'invoice_id',
* );
* ```
*/
issueSummary(
invoiceID: string,
body: InvoiceIssueSummaryParams | null | undefined = {},
options?: RequestOptions,
): APIPromise<InvoiceIssueSummaryResponse> {
return this._client.post(path`/invoices/summary/${invoiceID}/issue`, { body, ...options });
}
/**
* This is a lighter-weight endpoint that returns a list of all
* [`Invoice`](/core-concepts#invoice) summaries for an account in a list format.
*
* These invoice summaries do not include line item details, minimums, maximums,
* and discounts, making this endpoint more efficient.
*
* The list of invoices is ordered starting from the most recently issued invoice
* date. The response also includes
* [`pagination_metadata`](/api-reference/pagination), which lets the caller
* retrieve the next page of results if they exist.
*
* By default, this only returns invoices that are `issued`, `paid`, or `synced`.
*
* When fetching any `draft` invoices, this returns the last-computed invoice
* values for each draft invoice, which may not always be up-to-date since Orb
* regularly refreshes invoices asynchronously.
*
* @example
* ```ts
* // Automatically fetches more pages as needed.
* for await (const invoiceListSummaryResponse of client.invoices.listSummary()) {
* // ...
* }
* ```
*/
listSummary(
query: InvoiceListSummaryParams | null | undefined = {},
options?: RequestOptions,
): PagePromise<InvoiceListSummaryResponsesPage, InvoiceListSummaryResponse> {
return this._client.getAPIList('/invoices/summary', Page<InvoiceListSummaryResponse>, {
query,
...options,
});
}
/**
* This endpoint allows an invoice's status to be set to the `paid` status. This
* can only be done to invoices that are in the `issued` or `synced` status.
*
* @example
* ```ts
* const invoice = await client.invoices.markPaid(
* 'invoice_id',
* { payment_received_date: '2023-09-22' },
* );
* ```
*/
markPaid(
invoiceID: string,
body: InvoiceMarkPaidParams,
options?: RequestOptions,
): APIPromise<Shared.Invoice> {
return this._client.post(path`/invoices/${invoiceID}/mark_paid`, { body, ...options });
}
/**
* This endpoint collects payment for an invoice. By default, it uses the
* customer's default payment method. Optionally, a shared payment token (SPT) can
* be provided to pay using agent-granted credentials instead. This action can only
* be taken on invoices with status "issued".
*
* @example
* ```ts
* const invoice = await client.invoices.pay('invoice_id', {
* shared_payment_token_id: 'shared_payment_token_id',
* });
* ```
*/
pay(invoiceID: string, body: InvoicePayParams, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.post(path`/invoices/${invoiceID}/pay`, { body, ...options });
}
/**
* This endpoint triggers a regeneration of the PDF for a finalized invoice.
*
* The invoice must be finalized (`issued`, `paid`, `synced`, or `void`) and must
* already have an existing PDF. The original PDF is archived (not permanently
* deleted) to maintain an audit trail.
*
* **Important Legal Considerations:**
*
* Regenerating invoice PDFs may not be permitted in all jurisdictions. Many tax
* authorities require that issued invoices remain unmodified. Before using this
* endpoint, ensure that:
*
* - Your local tax regulations permit modification of issued billing documents
* - You have a legitimate business reason (e.g., fixing template errors, updating
* branding)
* - You maintain proper records of the original PDF (archived automatically by
* Orb)
*
* Recommended use cases:
*
* - Correcting template rendering issues
* - Applying updated company branding
* - Updating customer data that was incorrect at issuance
*
* @example
* ```ts
* const invoice = await client.invoices.regenerateInvoicePdf(
* 'invoice_id',
* );
* ```
*/
regenerateInvoicePdf(invoiceID: string, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.post(path`/invoices/${invoiceID}/regenerate_invoice_pdf`, options);
}
/**
* This endpoint triggers a regeneration of the receipt PDF for a paid invoice.
*
* The invoice must be in `paid` status and must already have an existing receipt
* PDF. The original PDF is archived (not permanently deleted) to maintain an audit
* trail.
*
* **Important Legal Considerations:**
*
* Regenerating receipt PDFs may not be permitted in all jurisdictions. Many tax
* authorities require that issued receipts remain unmodified. Before using this
* endpoint, ensure that:
*
* - Your local tax regulations permit modification of issued billing documents
* - You have a legitimate business reason (e.g., fixing template errors, updating
* branding)
* - You maintain proper records of the original PDF (archived automatically by
* Orb)
*
* Recommended use cases:
*
* - Correcting template rendering issues
* - Applying updated company branding
* - Updating customer data that was incorrect at issuance
*
* @example
* ```ts
* const invoice = await client.invoices.regenerateReceiptPdf(
* 'invoice_id',
* );
* ```
*/
regenerateReceiptPdf(invoiceID: string, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.post(path`/invoices/${invoiceID}/regenerate_receipt_pdf`, options);
}
/**
* This endpoint allows an invoice's status to be set to the `void` status. This
* can only be done to invoices that are in the `issued` status.
*
* If the associated invoice has used the customer balance to change the amount
* due, the customer balance operation will be reverted. For example, if the
* invoice used \$10 of customer balance, that amount will be added back to the
* customer balance upon voiding.
*
* If the invoice was used to purchase a credit block, but the invoice is not yet
* paid, the credit block will be voided. If the invoice was created due to a
* top-up, the top-up will be disabled.
*
* @example
* ```ts
* const invoice = await client.invoices.void('invoice_id');
* ```
*/
void(invoiceID: string, options?: RequestOptions): APIPromise<Shared.Invoice> {
return this._client.post(path`/invoices/${invoiceID}/void`, options);
}
}
export type InvoiceListSummaryResponsesPage = Page<InvoiceListSummaryResponse>;
export interface InvoiceFetchUpcomingResponse {
id: string;
/**
* This is the final amount required to be charged to the customer and reflects the
* application of the customer balance to the `total` of the invoice.
*/
amount_due: string;
auto_collection: InvoiceFetchUpcomingResponse.AutoCollection;
billing_address: Shared.Address | null;
/**
* The creation time of the resource in Orb.
*/
created_at: string;
/**
* A list of credit notes associated with the invoice
*/
credit_notes: Array<InvoiceFetchUpcomingResponse.CreditNote>;
/**
* An ISO 4217 currency string or `credits`
*/
currency: string;
customer: Shared.CustomerMinified;
customer_balance_transactions: Array<InvoiceFetchUpcomingResponse.CustomerBalanceTransaction>;
/**
* 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 |
* | Faroe Islands | `fo_vat` | Faroe Islands VAT Number |
* | 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 |
* | Gibraltar | `gi_tin` | Gibraltar Tax Identification 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 |
* | Italy | `it_cf` | Italian Codice Fiscale 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 |
* | Paraguay | `py_ruc` | Paraguayan RUC Number |
* | Peru | `pe_ruc` | Peruvian RUC Number |
* | Philippines | `ph_tin` | Philippines Tax Identification Number |
* | Poland | `eu_vat` | European VAT Number |
* | Poland | `pl_nip` | Polish Tax ID 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 |
* | Sri Lanka | `lk_vat` | Sri Lanka 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 |
*/
customer_tax_id: Shared.CustomerTaxID | null;
/**
* @deprecated This field is deprecated in favor of `discounts`. If a `discounts`
* list is provided, the first discount in the list will be returned. If the list
* is empty, `None` will be returned.
*/
discount: unknown;
discounts: Array<Shared.InvoiceLevelDiscount>;
/**
* When the invoice payment is due. The due date is null if the invoice is not yet
* finalized.
*/
due_date: string | null;
/**
* If the invoice has a status of `draft`, this will be the time that the invoice
* will be eligible to be issued, otherwise it will be `null`. If `auto-issue` is
* true, the invoice will automatically begin issuing at this time.
*/
eligible_to_issue_at: string | null;
/**
* A URL for the customer-facing invoice portal. This URL expires 60 days after the
* link is generated, or 30 days after the invoice's due date — whichever is later.
*/
hosted_invoice_url: string | null;
/**
* Automatically generated invoice number to help track and reconcile invoices.
* Invoice numbers have a prefix such as `RFOBWG`. These can be sequential per
* account or customer.
*/
invoice_number: string;
/**
* The link to download the PDF representation of the `Invoice`.
*/
invoice_pdf: string | null;
invoice_source: 'subscription' | 'partial' | 'one_off';
/**
* If the invoice failed to issue, this will be the last time it failed to issue
* (even if it is now in a different state.)
*/
issue_failed_at: string | null;
/**
* If the invoice has been issued, this will be the time it transitioned to
* `issued` (even if it is now in a different state.)
*/
issued_at: string | null;
/**
* The breakdown of prices in this invoice.
*/
line_items: Array<InvoiceFetchUpcomingResponse.LineItem>;
maximum: Shared.Maximum | null;
maximum_amount: string | null;
/**
* Free-form text which is available on the invoice PDF and the Orb invoice portal.
*/
memo: string | null;
/**
* 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`.
*/
metadata: { [key: string]: string };
minimum: Shared.Minimum | null;
minimum_amount: string | null;
/**
* If the invoice has a status of `paid`, this gives a timestamp when the invoice
* was paid.
*/
paid_at: string | null;
/**
* A list of payment attempts associated with the invoice
*/
payment_attempts: Array<InvoiceFetchUpcomingResponse.PaymentAttempt>;
/**
* If payment was attempted on this invoice but failed, this will be the time of
* the most recent attempt.
*/
payment_failed_at: string | null;
/**
* If payment was attempted on this invoice, this will be the start time of the
* most recent attempt. This field is especially useful for delayed-notification
* payment mechanisms (like bank transfers), where payment can take 3 days or more.
*/
payment_started_at: string | null;
/**
* If the invoice is in draft, this timestamp will reflect when the invoice is
* scheduled to be issued.
*/
scheduled_issue_at: string | null;
shipping_address: Shared.Address | null;
status: 'issued' | 'paid' | 'synced' | 'void' | 'draft';
subscription: Shared.SubscriptionMinified | null;
/**
* The total before any discounts and minimums are applied.
*/
subtotal: string;
/**
* If the invoice failed to sync, this will be the last time an external invoicing
* provider sync was attempted. This field will always be `null` for invoices using
* Orb Invoicing.
*/
sync_failed_at: string | null;
/**
* The scheduled date of the invoice
*/
target_date: string;
/**
* The total after any minimums and discounts have been applied.
*/
total: string;
/**
* If the invoice has a status of `void`, this gives a timestamp when the invoice
* was voided.
*/
voided_at: string | null;
/**
* This is true if the invoice will be automatically issued in the future, and
* false otherwise.
*/
will_auto_issue: boolean;
}
export namespace InvoiceFetchUpcomingResponse {
export interface AutoCollection {
/**
* True only if auto-collection is enabled for this invoice.
*/
enabled: boolean | null;
/**
* If the invoice is scheduled for auto-collection, this field will reflect when
* the next attempt will occur. If dunning has been exhausted, or auto-collection
* is not enabled for this invoice, this field will be `null`.
*/
next_attempt_at: string | null;
/**
* Number of auto-collection payment attempts.
*/
num_attempts: number | null;
/**
* If Orb has ever attempted payment auto-collection for this invoice, this field
* will reflect when that attempt occurred. In conjunction with `next_attempt_at`,
* this can be used to tell whether the invoice is currently in dunning (that is,
* `previously_attempted_at` is non-null, and `next_attempt_at` is non-null), or if
* dunning has been exhausted (`previously_attempted_at` is non-null, but
* `next_attempt_at` is null).
*/
previously_attempted_at: string | null;
}
export interface CreditNote {
id: string;
credit_note_number: string;
/**
* An optional memo supplied on the credit note.
*/
memo: string | null;
reason: string;
total: string;
type: string;
/**
* If the credit note has a status of `void`, this gives a timestamp when the
* credit note was voided.
*/
voided_at: string | null;
}
export interface CustomerBalanceTransaction {
/**
* A unique id for this transaction.
*/
id: string;
action:
| 'applied_to_invoice'
| 'manual_adjustment'
| 'prorated_refund'
| 'revert_prorated_refund'
| 'return_from_voiding'
| 'credit_note_applied'
| 'credit_note_voided'
| 'overpayment_refund'
| 'external_payment'
| 'small_invoice_carryover';
/**
* The value of the amount changed in the transaction.
*/
amount: string;
/**
* The creation time of this transaction.
*/
created_at: string;
credit_note: Shared.CreditNoteTiny | null;
/**
* An optional description provided for manual customer balance adjustments.
*/
description: string | null;
/**
* The new value of the customer's balance prior to the transaction, in the
* customer's currency.
*/
ending_balance: string;
invoice: Shared.InvoiceTiny | null;
/**
* The original value of the customer's balance prior to the transaction, in the
* customer's currency.
*/
starting_balance: string;
type: 'increment' | 'decrement';
}
export interface LineItem {
/**
* A unique ID for this line item.
*/
id: string;
/**
* The line amount after any adjustments and before overage conversion, credits and
* partial invoicing.
*/
adjusted_subtotal: string;
/**
* All adjustments applied to the line item in the order they were applied based on
* invoice calculations (ie. usage discounts -> amount discounts -> percentage
* discounts -> minimums -> maximums).
*/
adjustments: Array<
| Shared.MonetaryUsageDiscountAdjustment
| Shared.MonetaryAmountDiscountAdjustment
| Shared.MonetaryPercentageDiscountAdjustment
| LineItem.MonetaryTieredPercentageDiscountAdjustment
| Shared.MonetaryMinimumAdjustment
| Shared.MonetaryMaximumAdjustment
>;
/**
* The final amount for a line item after all adjustments and pre paid credits have
* been applied.
*/
amount: string;
/**
* The number of prepaid credits applied.
*/
credits_applied: string;
/**
* The end date of the range of time applied for this line item's price.
*/
end_date: string;
/**
* An additional filter that was used to calculate the usage for this line item.
*/
filter: string | null;
/**
* [DEPRECATED] For configured prices that are split by a grouping key, this will
* be populated with the key and a value. The `amount` and `subtotal` will be the
* values for this particular grouping.
*/
grouping: string | null;
/**
* The name of the price associated with this line item.
*/
name: string;
/**
* Any amount applied from a partial invoice
*/
partially_invoiced_amount: string;
/**
* 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](/core-concepts#plan-and-price)
*/
price: Shared.Price;
/**
* Either the fixed fee quantity or the usage during the service period.
*/
quantity: number;
/**
* The start date of the range of time applied for this line item's price.
*/
start_date: string;
/**
* For complex pricing structures, the line item can be broken down further in
* `sub_line_items`.
*/
sub_line_items: Array<Shared.MatrixSubLineItem | Shared.TierSubLineItem | Shared.OtherSubLineItem>;
/**
* The line amount before any adjustments.
*/
subtotal: string;
/**
* An array of tax rates and their incurred tax amounts. Empty if no tax
* integration is configured.
*/
tax_amounts: Array<Shared.TaxAmount>;
/**
* A list of customer ids that were used to calculate the usage for this line item.
*/
usage_customer_ids: Array<string> | null;
}
export namespace LineItem {
export interface MonetaryTieredPercentageDiscountAdjustment {
id: string;
adjustment_type: 'tiered_percentage_discount';
/**
* The value applied by an adjustment.
*/
amount: string;
/**
* @deprecated The price IDs that this adjustment applies to.
*/
applies_to_price_ids: Array<string>;
/**
* The filters that determine which prices to apply this adjustment to.
*/
filters: Array<MonetaryTieredPercentageDiscountAdjustment.Filter>;
/**
* True for adjustments that apply to an entire invoice, false for adjustments that
* apply to only one price.
*/
is_invoice_level: boolean;
/**
* The reason for the adjustment.
*/
reason: string | null;
/**
* The adjustment id this adjustment replaces. This adjustment will take the place
* of the replaced adjustment in plan version migrations.
*/
replaces_adjustment_id: string | null;
/**
* The ordered, contiguous bands of cumulative eligible spend, each discounted at
* its own percentage (progressive fill-a-tier), applied to the prices this
* adjustment covers in a given billing period.
*/
tiers: Array<MonetaryTieredPercentageDiscountAdjustment.Tier>;
}
export namespace MonetaryTieredPercentageDiscountAdjustment {
export interface Filter {
/**
* The property of the price to filter on.
*/
field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
/**
* Should prices that match the filter be included or excluded.
*/
operator: 'includes' | 'excludes';
/**
* The IDs or values that match this filter.
*/
values: Array<string>;
}
/**
* One band of a tiered percentage discount. Bounds are denominated in the
* discount's currency. `lower_bound` is the exclusive start of the band and
* `upper_bound` is the inclusive end; `upper_bound` is null only for the
* open-ended final tier.
*/
export interface Tier {
/**
* Exclusive lower bound of cumulative spend for this tier.
*/
lower_bound: number;
/**
* The percentage (between 0 and 1) discounted from spend that falls within this
* tier.
*/
percentage: number;
/**
* Inclusive upper bound of cumulative spend for this tier; null for the final
* open-ended tier.
*/
upper_bound?: number | null;
}
}
}
export interface PaymentAttempt {
/**
* The ID of the payment attempt.
*/
id: string;
/**
* The amount of the payment attempt.
*/
amount: string;
/**
* The time at which the payment attempt was created.
*/
created_at: string;
/**
* The