Skip to main content

Invoices

The Invoices API allows you to create, manage, and finalize invoices. It provides comprehensive functionality for handling various billing scenarios, including one-time payments, recurring subscriptions, and credit-based billing. You can retrieve detailed invoice information, apply discounts, manage staking operations, and search through historical records.

For more information on related features, see Subscriptions and Credit-Based Billing.

Retrieve an Invoice

Retrieves the details of an existing invoice. This method returns a comprehensive invoice object, including line items, applied discounts, related credit grants, and payment information.

Parameters

  • id string (required) — The unique identifier of the invoice to retrieve.

Returns

  • Invoice object — An Invoice object with expanded details. See TInvoiceExpanded and the additional properties below for the full structure.
    • discountDetails array — Details of discounts applied to the invoice.
      • coupon object — The coupon associated with the discount.
      • promotionCode object — The promotion code used to apply the discount.
    • relatedInvoice object — Information about a related invoice, if applicable (e.g., for credit notes).
    • relatedCreditGrants array — A list of credit grants created as a result of this invoice being paid.
    • paymentLink object — The payment link used to create the checkout session for this invoice.
    • checkoutSession object — The checkout session associated with this invoice.

Retrieve an Invoice

javascript
import payment from '@blocklet/payment-js';

async function getInvoice(invoiceId) {
  try {
    const invoice = await payment.invoices.retrieve(invoiceId);
    console.log('Retrieved Invoice:', invoice.id);
    console.log('Discount Details:', invoice.discountDetails);
    console.log('Related Credit Grants:', invoice.relatedCreditGrants);
  } catch (error) {
    console.error('Error retrieving invoice:', error.message);
  }
}

// Example usage:
getInvoice('inv_xxxxxxxxxxxxxx');

List Invoices

Returns a paginated list of your invoices. You can filter the list based on various criteria such as status, customer, or subscription.

Parameters

  • status string — A comma-separated string of invoice statuses to filter by (e.g., paid,open).
  • customer_id string — Filter invoices by a specific customer ID.
  • customer_did string — Filter invoices by the customer's DID.
  • subscription_id string — Filter invoices by a specific subscription ID.
  • currency_id string — Filter invoices by a specific currency ID.
  • ignore_zero boolean (default: false) — If true, invoices with a subtotal of zero will be excluded.
  • include_staking boolean (default: false) — If true, staking-related invoices will be included in the results.
  • include_return_staking boolean (default: false) — If true, invoices related to returned stakes will be included.
  • include_overdraft_protection boolean (default: true) — If true, invoices for stake overdraft protection will be included.
  • include_recovered_from boolean (default: false) — If true, invoices from previous subscriptions in a recovery chain will be included.
  • metadata.{key} string — Filter by custom metadata fields. Replace {key} with your metadata key.
  • page number (default: 1) — The page number for pagination.
  • pageSize number (default: 20) — The number of items to return per page.

Returns

  • PaginatedInvoices object — An object containing a list of invoices and pagination information.
    • list array — An array of Invoice objects.
    • count number — The total number of invoices matching the filter criteria.
    • paging object — Pagination details.
      • page number — The current page number.
      • pageSize number — The number of items per page.

List Invoices

javascript
import payment from '@blocklet/payment-js';

async function listPaidInvoices() {
  try {
    const invoices = await payment.invoices.list({
      status: 'paid',
      customer_id: 'cus_xxxxxxxxxxxxxx',
      ignore_zero: true,
      pageSize: 10,
    });
    console.log(`Found ${invoices.count} paid invoices.`);
    invoices.list.forEach(invoice => {
      console.log(`- Invoice ID: ${invoice.id}, Amount: ${invoice.total}`);
    });
  } catch (error) {
    console.error('Error listing invoices:', error.message);
  }
}

listPaidInvoices();

Search Invoices

Performs a search for invoices matching a query string across various fields like invoice number, customer details, and line item descriptions.

Parameters

  • q string (required) — The search query string.
  • page number (default: 1) — The page number for pagination.
  • pageSize number (default: 20) — The number of items to return per page.

Returns

  • PaginatedInvoices object — An object containing a list of invoices and pagination information.
    • list array — An array of Invoice objects.
    • count number — The total number of invoices matching the search criteria.
    • paging object — Pagination details.
      • page number — The current page number.
      • pageSize number — The number of items per page.

Search Invoices

javascript
import payment from '@blocklet/payment-js';

async function searchForInvoice(query) {
  try {
    const results = await payment.invoices.search({ q: query, pageSize: 5 });
    console.log(`Found ${results.count} results for query: '${query}'`);
    results.list.forEach(invoice => {
      console.log(`- Invoice ID: ${invoice.id}, Customer: ${invoice.customer.did}`);
    });
  } catch (error) {
    console.error('Error searching invoices:', error.message);
  }
}

// Example usage:
searchForInvoice('Premium Plan');

Update an Invoice

Updates the specified invoice by setting the metadata key-value pairs. Other invoice properties are generally not updatable.

Parameters

  • id string (required) — The unique identifier of the invoice to update.
  • metadata object — A set of key-value pairs to store with the invoice object. Keys can be up to 40 characters long and values can be up to 500 characters long.

Returns

  • Invoice object — The updated Invoice object.

Update Invoice Metadata

javascript
import payment from '@blocklet/payment-js';

async function updateInvoiceMetadata(invoiceId) {
  try {
    const updatedInvoice = await payment.invoices.update(invoiceId, {
      metadata: { order_id: 'order_12345' },
    });
    console.log('Invoice metadata updated:', updatedInvoice.metadata);
  } catch (error) {
    console.error('Error updating invoice:', error.message);
  }
}

// Example usage:
updateInvoiceMetadata('inv_xxxxxxxxxxxxxx');

Void an Invoice

Voids an invoice. This action is only possible on an invoice that is open or uncollectible. Once voided, an invoice cannot be paid.

Parameters

  • id string (required) — The unique identifier of the invoice to void.

Returns

  • Invoice object — The voided Invoice object, with its status set to void.

Void an Invoice

javascript
import payment from '@blocklet/payment-js';

async function voidInvoice(invoiceId) {
  try {
    const voidedInvoice = await payment.invoices.void(invoiceId);
    console.log(`Invoice ${voidedInvoice.id} has been voided. Status: ${voidedInvoice.status}`);
  } catch (error) {
    console.error('Error voiding invoice:', error.message);
  }
}

// Example usage:
voidInvoice('inv_xxxxxxxxxxxxxx');

Get Return Stake Information

Retrieves the amount of stake that can be returned for a stake or stake_overdraft_protection invoice.

Parameters

  • id string (required) — The identifier of the staking invoice.

Returns

  • StakeInfo object — An object containing details about the remaining stake.

Get Returnable Stake

javascript
import payment from '@blocklet/payment-js';

async function getStakeInfo(invoiceId) {
  try {
    const stakeInfo = await payment.invoices.getReturnStake(invoiceId);
    console.log('Returnable Stake Information:', stakeInfo);
  } catch (error) {
    console.error('Error getting stake info:', error.message);
  }
}

// Example usage:
getStakeInfo('inv_stake_xxxxxx');

Return Stake

Initiates the process of returning a stake associated with a paid stake or stake_overdraft_protection invoice.

Parameters

  • id string (required) — The identifier of the staking invoice.

Returns

  • ReturnResult object — An object indicating the result of the operation.
    • success boolean — Indicates if the return stake process was successfully initiated.
    • subscriptionId string — The ID of the associated subscription.
    • error string — An error message if the operation failed.

Return a Stake

javascript
import payment from '@blocklet/payment-js';

async function returnStake(invoiceId) {
  try {
    const result = await payment.invoices.returnStake(invoiceId);
    if (result.success) {
      console.log(`Stake return initiated for subscription: ${result.subscriptionId}`);
    } else {
      console.error('Failed to return stake:', result.error);
    }
  } catch (error) {
    console.error('Error returning stake:', error.message);
  }
}

// Example usage:
returnStake('inv_stake_xxxxxx');