# Invoice Aggregation API



<EndpointIndex
  names={[
  	'fetchInvoicesForAggregateInvoice',
  	'getInvoiceDetailsAttachedToAggregate',
  	'createAggregateInvoice',
  	'patchAggregateInvoice',
  	'transferInvoicesBetweenAggregateInvoices',
  	'discardAggregateInvoice',
  ]}
  titles={{
  	fetchInvoicesForAggregateInvoice: 'Fetch Invoices for Aggregate Invoice',
  	getInvoiceDetailsAttachedToAggregate:
  		'Fetch Invoice Details for Aggregate Invoice',
  	createAggregateInvoice: 'Create Aggregate Invoice',
  	patchAggregateInvoice: 'Update Aggregate Invoice',
  	transferInvoicesBetweenAggregateInvoices:
  		'Transfer Invoices Between Aggregate Invoices',
  	discardAggregateInvoice: 'Discard Aggregate Invoice',
  }}
/>

Fetch Invoices for Aggregate Invoice [#fetch-invoices-for-aggregate-invoice]

<ApiEndpoint name="fetchInvoicesForAggregateInvoice" title="Fetch Invoices for Aggregate Invoice" />

<ApiSchema name="ListPageResponseInvoiceSummaryView" />

Fetch Invoice Details for Aggregate Invoice [#fetch-invoice-details-for-aggregate-invoice]

<ApiEndpoint name="getInvoiceDetailsAttachedToAggregate" title="Fetch Invoice Details for Aggregate Invoice" />

<ApiSchema name="ListPageResponseInvoiceDetails" />

Create Aggregate Invoice [#create-aggregate-invoice]

<ApiEndpoint name="createAggregateInvoice" title="Create Aggregate Invoice" />

This endpoint returns the new invoice with `invoiceType` set to `aggregate` and empty `invoiceItems`. Its `invoiceState` is `open`, or `settled` if none of the included invoices are open.

<ApiSchema name="AggregateInvoiceCreateRequest" />

Update Aggregate Invoice [#update-aggregate-invoice]

<ApiEndpoint name="patchAggregateInvoice" title="Update Aggregate Invoice" />

This endpoint returns the updated aggregate invoice. At least one body parameter is required, and no locator may appear in both `addInvoices` and `removeInvoices`. Omitted parameters keep their current values. Dates are not recalculated when invoices are added or removed.

<ApiSchema name="AggregateInvoicePatchRequest" />

Transfer Invoices Between Aggregate Invoices [#transfer-invoices-between-aggregate-invoices]

<ApiEndpoint name="transferInvoicesBetweenAggregateInvoices" title="Transfer Invoices Between Aggregate Invoices" />

This endpoint returns the source aggregate invoice. Both the source and destination re-evaluate their state afterwards.

<ApiSchema name="AggregateInvoiceTransferRequest" />

Discard Aggregate Invoice [#discard-aggregate-invoice]

<ApiEndpoint name="discardAggregateInvoice" title="Discard Aggregate Invoice" />


## API Reference

GET /billing/{tenantLocator}/invoices/{locator}/invoices/list — fetchInvoicesForAggregateInvoice
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 ListPageResponseInvoiceSummaryView — OK

GET /billing/{tenantLocator}/invoices/{locator}/invoices/details/list — getInvoiceDetailsAttachedToAggregate
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 ListPageResponseInvoiceDetails — OK

POST /billing/{tenantLocator}/invoices — createAggregateInvoice
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
Request body (AggregateInvoiceCreateRequest):
Responses:
  200 InvoiceResponse — OK

PATCH /billing/{tenantLocator}/invoices/{locator}/aggregate — patchAggregateInvoice
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (AggregateInvoicePatchRequest):
Responses:
  200 InvoiceResponse — OK

POST /billing/{tenantLocator}/invoices/{locator}/transfer — transferInvoicesBetweenAggregateInvoices
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (AggregateInvoiceTransferRequest):
Responses:
  200 InvoiceResponse — OK

PATCH /billing/{tenantLocator}/invoices/{locator}/discard — discardAggregateInvoice
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 InvoiceResponse — OK

ListPageResponseInvoiceSummaryView
Properties:
  listCompleted (boolean, required)
  items (InvoiceSummaryView[], required)

ListPageResponseInvoiceDetails
Properties:
  listCompleted (boolean, required)
  items (InvoiceDetailsResponse[], required)

AggregateInvoiceCreateRequest
Properties:
  accountLocator (ulid, required) — The account associated with the aggregate invoice.
  invoiceLocators (ulid[], required) — Up to 100, no duplicates. Each must belong to the account, share one currency, and not already be on an aggregate invoice. May be empty or omitted.
  startTime (datetime) — Defaults to the earliest `startTime` of the included invoices, or the creation time if not present. Must be before `endTime`.
  endTime (datetime) — Defaults to the latest `endTime` of the included invoices, or the creation time if not present.
  dueTime (datetime) — Defaults to the earliest `dueTime` of the included invoices, or the creation time if not present.
  currency (string) — Must match the included invoices. Defaults to their currency, then the tenant default.
  timezone (string) — Defaults to the shared timezone of the included invoices, then the account timezone, then the tenant default.

AggregateInvoicePatchRequest
Properties:
  startTime (datetime) — Must be before `endTime`.
  endTime (datetime)
  dueTime (datetime)
  currency (string) — Must match the contained invoices.
  timezone (string)
  addInvoices (ulid[], required) — Up to 100, no duplicates. Each must belong to the account, share one currency, and not already be on an aggregate invoice.
  removeInvoices (ulid[], required) — Up to 100, no duplicates. Locators not on this aggregate invoice are ignored.

AggregateInvoiceTransferRequest
Properties:
  targetAggregateInvoiceLocator (ulid, required) — The destination aggregate invoice. Must differ from the source and belong to the same account.
  invoiceLocators (ulid[], required) — 1 to 100, no duplicates, and each must currently be on the source.