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#
The unique identifier of the invoice to retrieve.
Returns#
An Invoice object with expanded details. See TInvoiceExpanded and the additional properties below for the full structure.
Retrieve an Invoice
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#
A comma-separated string of invoice statuses to filter by (e.g., paid,open).
If true, invoices with a subtotal of zero will be excluded.
If true, staking-related invoices will be included in the results.
If true, invoices related to returned stakes will be included.
If true, invoices for stake overdraft protection will be included.
If true, invoices from previous subscriptions in a recovery chain will be included.
Filter by custom metadata fields. Replace {key} with your metadata key.
Returns#
An object containing a list of invoices and pagination information.
List Invoices
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#
The search query string.
Returns#
An object containing a list of invoices and pagination information.
Search Invoices
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#
The unique identifier of the invoice to update.
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#
The updated Invoice object.
Update Invoice Metadata
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#
The unique identifier of the invoice to void.
Returns#
The voided Invoice object, with its status set to void.
Void an Invoice
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#
The identifier of the staking invoice.
Returns#
An object containing details about the remaining stake.
Get Returnable Stake
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#
The identifier of the staking invoice.
Returns#
An object indicating the result of the operation.
Return a Stake
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');