orb-billing
Version:
The official TypeScript library for the Orb API
330 lines • 13.1 kB
JavaScript
;
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
Object.defineProperty(exports, "__esModule", { value: true });
exports.Invoices = void 0;
const resource_1 = require("../core/resource.js");
const pagination_1 = require("../core/pagination.js");
const headers_1 = require("../internal/headers.js");
const path_1 = require("../internal/utils/path.js");
/**
* 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.
*/
class Invoices extends resource_1.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, options) {
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, body, options) {
return this._client.put((0, path_1.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 = {}, options) {
return this._client.getAPIList('/invoices', (pagination_1.Page), { 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, params, options) {
const { invoice_id } = params;
return this._client.delete((0, path_1.path) `/invoices/${invoice_id}/invoice_line_items/${lineItemID}`, {
...options,
headers: (0, headers_1.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, options) {
return this._client.get((0, path_1.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, options) {
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, body = {}, options) {
return this._client.post((0, path_1.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, body = {}, options) {
return this._client.post((0, path_1.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 = {}, options) {
return this._client.getAPIList('/invoices/summary', (pagination_1.Page), {
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, body, options) {
return this._client.post((0, path_1.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, body, options) {
return this._client.post((0, path_1.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, options) {
return this._client.post((0, path_1.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, options) {
return this._client.post((0, path_1.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, options) {
return this._client.post((0, path_1.path) `/invoices/${invoiceID}/void`, options);
}
}
exports.Invoices = Invoices;
//# sourceMappingURL=invoices.js.map