Socotra
API ReferenceBilling API

Invoice Aggregation API

ActionEndpoint
Fetch Invoices for Aggregate InvoiceGET/billing/{tenantLocator}/invoices/{locator}/invoices/list
Fetch Invoice Details for Aggregate InvoiceGET/billing/{tenantLocator}/invoices/{locator}/invoices/details/list
Create Aggregate InvoicePOST/billing/{tenantLocator}/invoices
Update Aggregate InvoicePATCH/billing/{tenantLocator}/invoices/{locator}/aggregate
Transfer Invoices Between Aggregate InvoicesPOST/billing/{tenantLocator}/invoices/{locator}/transfer
Discard Aggregate InvoicePATCH/billing/{tenantLocator}/invoices/{locator}/discard

Fetch Invoices for Aggregate Invoice

Fetch Invoices for Aggregate InvoicefetchInvoicesForAggregateInvoice
GET/billing/{tenantLocator}/invoices/{locator}/invoices/list

Parameters

NameInTypeRequiredDescription
tenantLocatorpathuuidYes
locatorpathulidYes
offsetqueryinteger?No
countqueryinteger?No
Security Group:invoices
Permissions:
read,list

ListPageResponseInvoiceSummaryView

Required properties

PropertyTypeDescription
listCompletedboolean
itemsInvoiceSummaryView[]

Fetch Invoice Details for Aggregate Invoice

Fetch Invoice Details for Aggregate InvoicegetInvoiceDetailsAttachedToAggregate
GET/billing/{tenantLocator}/invoices/{locator}/invoices/details/list

Parameters

NameInTypeRequiredDescription
tenantLocatorpathuuidYes
locatorpathulidYes
offsetqueryinteger?No
countqueryinteger?No
Security Group:invoices
Permissions:
read,list

ListPageResponseInvoiceDetails

Required properties

PropertyTypeDescription
listCompletedboolean
itemsInvoiceDetailsResponse[]

Create Aggregate Invoice

Create Aggregate InvoicecreateAggregateInvoice
POST/billing/{tenantLocator}/invoices

Parameters

NameInTypeRequiredDescription
tenantLocatorpathuuidYes
Security Group:invoices
Permission:
write

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.

AggregateInvoiceCreateRequest

Required properties

PropertyTypeDescription
accountLocatorulidThe account associated with the aggregate invoice.
invoiceLocatorsulid[]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.

Optional properties

PropertyTypeDescription
startTimedatetime?Defaults to the earliest startTime of the included invoices, or the creation time if not present. Must be before endTime.
endTimedatetime?Defaults to the latest endTime of the included invoices, or the creation time if not present.
dueTimedatetime?Defaults to the earliest dueTime of the included invoices, or the creation time if not present.
currencystring?Must match the included invoices. Defaults to their currency, then the tenant default.
timezonestring?Defaults to the shared timezone of the included invoices, then the account timezone, then the tenant default.

Update Aggregate Invoice

Update Aggregate InvoicepatchAggregateInvoice
PATCH/billing/{tenantLocator}/invoices/{locator}/aggregate

Parameters

NameInTypeRequiredDescription
tenantLocatorpathuuidYes
locatorpathulidYes
Security Group:invoices
Permission:
write

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.

AggregateInvoicePatchRequest

Required properties

PropertyTypeDescription
addInvoicesulid[]Up to 100, no duplicates. Each must belong to the account, share one currency, and not already be on an aggregate invoice.
removeInvoicesulid[]Up to 100, no duplicates. Locators not on this aggregate invoice are ignored.

Optional properties

PropertyTypeDescription
startTimedatetime?Must be before endTime.
endTimedatetime?
dueTimedatetime?
currencystring?Must match the contained invoices.
timezonestring?

Transfer Invoices Between Aggregate Invoices

Transfer Invoices Between Aggregate InvoicestransferInvoicesBetweenAggregateInvoices
POST/billing/{tenantLocator}/invoices/{locator}/transfer

Parameters

NameInTypeRequiredDescription
tenantLocatorpathuuidYes
locatorpathulidYes
Security Group:invoices
Permission:
write

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

AggregateInvoiceTransferRequest

Required properties

PropertyTypeDescription
targetAggregateInvoiceLocatorulidThe destination aggregate invoice. Must differ from the source and belong to the same account.
invoiceLocatorsulid[]1 to 100, no duplicates, and each must currently be on the source.

Discard Aggregate Invoice

Discard Aggregate InvoicediscardAggregateInvoice
PATCH/billing/{tenantLocator}/invoices/{locator}/discard

Parameters

NameInTypeRequiredDescription
tenantLocatorpathuuidYes
locatorpathulidYes
Security Group:invoices
Permission:
write

On this page