API Reference

Bulk Operations

Bulk Payable. Uploads

Overview

The Bulk Payable Upload Service allows clients to efficiently create and manage multiple payable items (invoices or deductions) in bulk. This service is designed to handle high-volume payable operations by grouping payable items into batches and processing them asynchronously.

Core Concepts

Bulk Payable Batch

A Bulk Payable Batch represents a collection of payable items to be processed together. Batches help organize and manage multiple payables efficiently. Each batch has the following attributes:

  • bulkPayableBatchId: Unique identifier for the batch.
  • clientId: Identifier of the client creating the batch.
  • status: Current status of the batch (e.g., Open, Pending, Processing, Complete, Failed).
  • processingStrategy: Strategy for processing items within the batch (Single or Merge).
  • labels: Optional key-value pairs for custom metadata.

Bulk Payable Item

A Bulk Payable Item represents an individual payable within a batch. Each item corresponds to an invoice to be sent or a deduction to be applied. Attributes include:

  • bulkPayableItemId: Unique identifier for the item.
  • bulkPayableBatchId: Identifier of the batch the item belongs to.
  • clientId: Identifier of the client associated with the item.
  • amount: Amount of the payable (positive for invoices, negative for deductions).
  • status: Current status of the item (Open, Complete, Failed).
  • payableStatus: Desired status of the resulting payable (Draft, Open, Approved, Paid, Cancelled).
  • collaboratorEmail, collaboratorId, collaboratorExternalId: Information to identify the collaborator.
  • dueDate: Due date for the payable.
  • paidDate: Paid date for the payable (if already paid).
  • lineItemDescription: Description of the line item.
  • labels: Optional key-value pairs for custom metadata.
  • metadata: Additional data, such as resolved collaborator IDs or error messages.

Statuses

Both batches and items can have various statuses reflecting their state in the processing lifecycle:

  • Open: Ready for adding items or processing.
  • Pending: Awaiting processing.
  • Processing: Currently being processed.
  • Complete: Successfully processed.
  • Failed: Processing failed due to errors.

Processing Strategies

Defines how items within a batch are processed:

  • Single: Each item is processed independently, resulting in separate payables.
  • Merge: Items with the same bulkPayableItemMergeKey are merged into a single payable.