consolidatedinvoices
The consolidatedinvoices
endpoint retrieves your reseller invoices and attempts to match customer sales prices in the same element. This merged set of reseller costs and customer sales prices are provided on a best-effort base.
Please note
The cloud platform currently does not provide a unique reference number to reliably match reseller and customer invoices on the line item level. This billing API endpoint uses a custom algorithm that attempts to match reseller invoice lines to customer sales prices. This algorithm/endpoint is not perfect and might not return all lines, return lines more than once, or mismatch to wrong customer lines. See the Versioningsection for currently known issues in this endpoint.
Use this endpoint at your own risk. We recommend using the “Invoices“ and/or “CustomerInvoices“ endpoints instead for reliably retrieving billing data from the cloud platform.
The endpoint returns invoice data, grouped per invoice, per customer, per subscription, and specified per invoice line.
Example response in JSON format.
{
"Invoices":
[
{
"Customers":
[
{
"AccountID": ......,
"CompanyName": "......",
"CustomerCostCenter": ......,
"CustomerNumber": "......",
"Subscriptions":
[
{
"PriceLines":
[
{
"Description": "......",
"Duration": ......,
"DurationType": "......",
"EndDate": "......",
"LineId": ......,
"PurchaseDiscount": ......,
"PurchasePrice": ......,
"PurchaseVAT": ......,
"Quantity": ......,
"QuantityType": "......",
"SalesDiscount": ......,
"SalesPrice": ......,
"SalesVAT": ......,
"SKU": "......",
"StartDate": "......",
"TaxPercentage": ......,
"TaxZoneID": "......",
"UID": "......",
"UnitPrice": ......
}
],
"StartDate": "......",
"ExpirationDate": "......",
"SubscriptionID": ......,
"SubscriptionName": "......"
}
]
}
],
"Header":
{
"Currency": "EUR",
"Date": "......",
"Description": "......",
"ExpirationDate": "......",
"InvoiceID": "......",
"Language": "......",
"LanguageCode": "......",
"TermsOfPaymentDays": ......,
"Type": "......",
"TypeIdentifier": ......
},
"Receiver":
{
"AccountID": ......,
"Address": "......",
"City": "......",
"CompanyName": "......",
"ContactFirstName": "......",
"ContactLastName": "......",
"ContactMiddleName": "......",
"Country": "......",
"CountryCode": "......",
"CustomerNumber": "......",
"Email": "......",
"Fax": ......,
"Telephone": "......",
"Type": ......,
"VATNumber": "......",
"Zip": "......"
},
"Sender":
{
"AccountID": ......,
"Address": "......",
"BankAccount": "......",
"BIC": "......",
"ChamberOfCommerce": "......",
"City": "......",
"CompanyName": "......",
"Country": "......",
"CountryCode": "......",
"Fax": "......",
"IBAN": "......",
"Logo": "......",
"PostalCode": "......",
"Telephone": "......",
"VATNumber": "......",
"Website": "......"
},
"Totals":
{
"TotalPurchases":
{
"TotalExcludingVAT": ......,
"TotalIncludingVAT": ......,
"TotalVAT": ......
},
"TotalSales":
{
"TotalExcludingVAT": ......,
"TotalIncludingVAT": ......,
"TotalVAT": ......
}
}
}
]
}
The ConsolidatedInvoice endpoint contains one <Invoices>
element which is a collection of 1 or more <Invoice>
elements . This <Invoice>
consists of a <Header>
, <Sender>
, <Receiver>
, <Customers>
and <Totals>
element.
Invoice element
The Invoices
element contains information about one single invoice.
Each Invoice
consists of:
Element | Description |
---|---|
| element |
| element |
| element |
| element containing 1 or more |
| element consisting of sub-elements. |
Header element
The Header
element contains basic information about the Invoice
. It has the following child elements:
Element | Description |
---|---|
| The identifying number of the invoice, like |
| Invoice date, like |
| Payment due date of the invoice, like |
| Currency, like |
| Terms of payment in days, like |
| Type of document provided, like |
| Type Code of document corresponding to the type, like |
| Language code used to create the printed version of the document, like |
| The language used to create the printed version of the document, like |
| Invoice description, like |
Sender element
This Sender
element has information about the Sender. It has the following child elements:
Element | Description |
---|---|
| Sender Account ID as shown in the Cloud management portal, like |
| Name of the Sender of the document, like |
| Street the Sender is registered at the chamber of commerce, like |
| Postal code of the Sender, like |
| City the Sender is registered in the Chamber of Commerce, like |
| Specific code for the country of the Sender |
| Country the Sender is registered at the chamber of commerce |
| Sender contact telephone number |
| Sender contact fax number |
| Number of the Sender as registered in the Chamber of Commerce |
| Number of Sender's Bank account |
| IBAN Number of the Sender |
| Bank Identifier Code of the Sender's bank account |
| VAT number of the Sender |
| Sender's website |
| Publicly accessible URL to your company logo, to place the company logo on the print version of the invoice |
Receiver element
The Receiver
element in an Invoice contains info about the receiving Partner and has the following child elements:
Element | Description |
---|---|
| Receiver Account ID corresponding to that in the 2tCloud Portal |
| Corresponds with the Copaco customer account number |
| Name of the Partner |
| VAT number of the Partner |
| Billing contact first name |
| Billing contact middle name |
| Billing contact last name |
| Street the partner is registered at the chamber of commerce |
| Zip code the partner is registered at the chamber of commerce |
| City the partner is registered at the chamber of commerce |
| Specific code for the country of the Receiver |
| Corresponding country the partner registered at the chamber of commerce |
| Billing contact telephone number |
| Email Address the invoice is sent to |
| Billing contact Fax number |
| Relates to the Account and specifies whether it is a Reseller or an EndCustomer.
|
Customer element
An Invoice
normally has a Customers
child element. This contains 1 or more Customer
elements. The child elements of Customer
are:
Element | Description |
---|---|
| Corresponding to the ID in the Copaco Cloud Portal |
| Can be used by the Partner for reference to own ERP system. This number is set in the Control Panel at the additional information tab in the billing section |
|
|
| Name of the Customer |
| Element that consists of 1 or more |
Subscription element
The Subscription
contains basic information about a customer's subscription as well as several LineItem
elements with detailed info.
Element | Description |
---|---|
| Corresponds to the subscription in the Platform |
| Name of the subscription |
| An integer number, referring to a specific billing model like Pay before the subscription period, pay after the subscription period, pay as you go, or Externally rated. |
| An integer number, referring to the unique service plan ID that the subscription is based on. |
| Contains a list of names given to the service plan in different languages. |
| Internal identifier for the product category for the service plan |
| Initial start date of the subscription |
| Relative date field that contains the current subscription expiration date. Please note that this field will be updated automatically on the renewal moment and set to a new future date as long as the auto-renewal feature is activated. |
| PO Number of the Subscription (can be filled in by the Reseller) |
| Element containing a collection of 1 or more |
LineItem element
A LineItem
contains detailed information about its parent in this case of a Subscription. Below are the child elements of LineItem
further explained:
Element | Description |
---|---|
| Identification number as stored in the Copaco Cloud portal |
| The first UID is corresponding to the identifying number configured in the plan starting with a P form ‘plan’. The second and every UID after until the next subscription starts with a R from ‘resource’. A resource is an addition to the initial subscription |
| First line item contains the subscription #number and description. Successive line items contain the resource name of the line item belonging to the subscription |
| First quantity contains the amount of in the subscription included resources. Successive line items contain number of resources of the line item belonging to the subscription |
| Specifies the type of the Quantity (e.g. item) |
| Price of the line item the Customer can order the item for |
| The total discount of all included resources |
| The amount to be paid for the line item |
| Amount of VAT applicable for the line item |
| Corresponds to the ID configured in the Platform at a subscription level |
| Percentage applicable to the line item |
| Start date of the subscription period |
| End date of the subscription period |
| Duration of one subscription period (1, 3, etc), to be used in combination with |
| Duration type e.g. Month(s), Year |
| By the Partner configured SKU number of the subscription period recurring fee. This field is empty by default. |
| Unique internal ID (integer value) of the company account. |
| Name of the Customer |
| PO Number at LineItem level (currently same as on subscription level) |
| Internal Identifier of the resource rate period in the platform, unique per reseller. |
Totals element
An Invoice
normally ends with a Totals
element where the accumulated price data of all the prior elements is stored. As result, it displays information about the total amount the Partner has to pay over all Customers
.
Typical for a consolidatedinvoice endpoint result is that the <Totals>
element consists of a <TotalPurchases>
and <TotalSales>
sub-element.
The <TotalPurchases>
and <TotalSales>
sub-elements consist of:
Element | Description |
---|---|
| Total amount in Euro excluding VAT |
| Total VAT in Euro, exclusive of telecommunication services |
| Total amount in Euro including VAT |