Skip to main content
resources/invoices.InvoiceClient The InvoiceClient handles operations related to invoices, which are records of sales or usage of licensed assets. Invoices are typically imported from external platforms (e.g., Roblox sales data) and are used as the basis for calculating and distributing royalties to rights holders. This client can import, fetch, and even generate mock invoice data for testing.

​
Table of contents

​
Methods

​
constructor

• new InvoiceClient(client): InvoiceClient

​
Parameters

NameType
clientSpaceportSDK

​
Returns

InvoiceClient

​
Methods

​
import

▸ import(params): Promise<ImportInvoicesResponse> Import invoices from a CSV file into the Directus database This method uploads a CSV file to the backend and processes it to create invoice records in the database. It can be used in preview mode to validate the data before actual import.

​
Parameters

NameTypeDescription
paramsImportInvoicesParamsImport parameters including CSV file and options

​
Returns

Promise<ImportInvoicesResponse> Promise resolving to import results Example 
// Preview import without saving
const previewResult = await sdk.invoices.import({
  csvFile: csvFile,
  agreementId: 'agreement-123',
  preview: true
});

console.log(`Would import ${previewResult.invoices.length} invoices`);

// Actual import
const importResult = await sdk.invoices.import({
  csvFile: csvFile,
  agreementId: 'agreement-123',
  preview: false
});

​
generateMockInvoiceData

▸ generateMockInvoiceData(options?): Promise<GeneratedInvoiceCSV> Generates mock Roblox invoice data for testing purposes This method creates realistic-looking invoice data distributed across quarters with randomized revenue and pricing data suitable for testing royalty calculations.

​
Parameters

NameTypeDescription
optionsGenerateInvoiceCSVOptionsConfiguration options for CSV generation

​
Returns

Promise<GeneratedInvoiceCSV> Promise resolving to generated CSV data and metadata Example 
// Generate 100 invoices across 4 quarters of 2024
const result = await sdk.invoices.generateMockInvoiceData({
  count: 100,
  startYear: 2024,
  quarters: 4,
  assetPlatformId: '123456789'
});

// Create a File object from the CSV content
const csvFile = new File([result.csvContent], 'mock-invoices.csv', {
  type: 'text/csv'
});

// Use with royalty registration
await sdk.royalties.register({
  csvFile: csvFile,
  productIds: [123, 456],
  userId: 'user-id',
  licenseeAddress: '0x...'
});

​
generateMockCSVFile

▸ generateMockCSVFile(filename?, options?): Promise<{ file: File ; metadata: Omit<GeneratedInvoiceCSV, "csvContent"> }> Generates a File object containing mock CSV data This is a convenience method that combines generateMockInvoiceData with File creation for direct use with file upload APIs.

​
Parameters

NameTypeDefault valueDescription
filenamestring'mock-invoices.csv'The filename for the generated file
optionsGenerateInvoiceCSVOptions{}Configuration options for CSV generation

​
Returns

Promise<{ file: File ; metadata: Omit<GeneratedInvoiceCSV, "csvContent"> }> Promise resolving to a File object and metadata Example 
const { file, metadata } = await sdk.invoices.generateMockCSVFile(
  'test-invoices.csv',
  { count: 50, startYear: 2024 }
);

// Use the file directly with royalty registration
await sdk.royalties.register({
  csvFile: file,
  productIds: [123],
  userId: 'user-id',
  licenseeAddress: '0x...'
});

​
getAll

▸ getAll(params?): Promise<Invoice[]> Fetch invoices from the backend with optional filtering This method retrieves invoice records from the database with support for various filters including product ID, date ranges, and status.

​
Parameters

NameTypeDescription
paramsFetchInvoicesParamsFetch parameters for filtering invoices

​
Returns

Promise<Invoice[]> Promise resolving to array of invoices Example 
// Fetch invoices for specific products
const invoices = await sdk.invoices.fetch({
  product_id: [123, 456],
  status: 'published'
});

// Fetch invoices within date range
const recentInvoices = await sdk.invoices.fetch({
  date_gte: new Date('2024-01-01'),
  date_lte: new Date('2024-12-31'),
  limit: 100
});