Billing API's

The invoices endpoint retrieves your purchase invoices for a specified period (Reseller Invoices). It contains the price data that you as a reseller pay to Copaco Cloud.

The endpoint returns invoice data, grouped per invoice and specified per customer and subscription.

The customer-specifications endpoint retrieves your sales invoices for a specified period (Customer Invoices). It contains the price data that your customers should pay to you as a reseller.

The endpoint returns invoice data, grouped per invoice and specified per customer and subscription.

Date filtering
The invoices and customer-specification endpoint can be filtered using query (url) parameters: startDate and endDate. The format required for these parameters is: YYYYMMDD. By default, when no dates or filtering is provided, the invoices for the last three months are returned (startDate = today - 3 months, endDate = today). The filtering applies to the date the invoice is created, not the period the invoice is about. For example: if you'd like to retrieve the invoice for the subscriptions of November, you would have to filter on December 18th till December 25th since the invoice for November will be created around December 23rd.

Invoice consolidation
In the Copaco Cloud platform, invoices are created per vendor. So if you or your customers have subscriptions for Azure and VMWare, two invoices will be created in the Copaco Cloud Platform. The PDF invoice, which is sent by email to the billing contact of your organization, is a consolidated invoice. This means that the invoices of the different vendors for that month will be combined into one. The Billing API does not consolidate the individual vendor invoices. These will be available in the Billing API as separate Invoice elements.

Example response in JSON format.

JSON

{
"Invoices":
    [
        {
        "Customers":
            [
                {
                "AccountID": ......,
                "CompanyName": "......",
                "CostCenter": "......",
                "CustomerNumber": "......",
                "Subscriptions":
                    [
                        {
                        "BillingModel": ......,
                        "PlanCategoryName": "......",
                        "PlanID": ......,
                        "PlanName": "......",
                        "PriceLines":
                            [
                                {
                                "ConsumerCompanyName": "......",
                                "ConsumerCompanyNumber": "......",
                                "Description": "......",
                                "Discount": ......,
                                "Duration": "......",
                                "DurationType": "......",
                                "BillingFrequency": "......",
                                "EndDate": "......",
                                "ExtendedPrice": ......,
                                "LineId": ......,
                                "Quantity": ......,
                                "QuantityType": "......",
                                "RatePeriodID": ......,
                                "SKU": "......",
                                "StartDate": "......",
                                "SubPONumber": ......,
                                "TaxPercentage": ......,
                                "TaxZoneID": "......",
                                "UID": "......",
                                "UnitPrice": ......,
                                "VAT": ......
                                }
                            ],
                        "StartDate": "......",
                        "SubscriptionID": ......,
                        "SubscriptionName": "......",
                        "SubscriptionPONumber": ......
						} 
                    ]
                }
            ],
        "Header":
            {
            "Currency": "......",
            "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":
            {
            "TotalExcludingVAT": ......,
            "TotalIncludingVAT": ......,
            "TotalVAT": ......
            }
        }
    ]
}

Invoice element

The Invoices element contains information about one single invoice. Each Invoice consists of:

Element	Description
`Header`	element
`Sender`	element
`Receiver`	element
`Customers`	element containing 1 or more `Customer` elements
`Totals`	element consisting of sub-elements.

Header element

The Header element contains basic information about the Invoice. It has the following child elements:

Element	Description
`InvoiceID`	The identifying number of the invoice
`Date`	Invoice date
`ExpirationDate`	Due date of the invoice
`Currency`	Currency, like `EUR`
`TermsOfPaymentDays`	Terms of payment days agreed upon
`Type`	Invoice or credit
`TypeIdentifier`	Code corresponding to the type
`LanguageCode`	Language code used by Copaco to create the printed version of the invoice
`Language`	The language used by Copaco to create the printed version of the invoice
`Description`	Invoice description

Sender element

This Sender element has information about the Sender. It has the following child elements:

Element	Description
`AccountID`	Sender Account ID as shown in the Cloud Platform
`CompanyName`	Company name of the sender
`Address`	Street the sender is registered at the chamber of commerce
`PostalCode`	Postal code of the sender
`City`	City the sender is registered in the Chamber of Commerce
`CountryCode`	Specific code for the country of the sender
`Country`	Country the sender is registered at the chamber of commerce
`Telephone`	Sender contact telephone number
`Fax`	Sender contact fax number
`ChamberOfCommerce`	Number of the sender as registered in the Chamber of Commerce
`BankAccount`	Number of sender's Bank account
`IBAN`	IBAN Number of the sender
`BIC`	Bank Identifier Code of the sender's bank account
`VATNumber`	VAT number of the sender
`Website`	Sender's website
`Logo`	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
`AccountID`	Receiver Account ID corresponding to that in the Cloud Platform
`CustomerNumber`	Corresponds with the Copaco customer account number. (This is the External Customer ID configured in the Cloud Platform)
`CompanyName`	Company name of the receiver
`VATNumber`	VAT number of the receiver
`ContactFirstName`	Billing contact first name
`ContactMiddleName`	Billing contact middle name
`ContactLastName`	Billing contact last name
`Address`	Street the receiver is registered at the chamber of commerce
`Zip`	Zip code the receiver is registered at the chamber of commerce
`City`	City the receiver is registered at the chamber of commerce
`CountryCode`	Specific code for the country of the receiver
`Country`	Corresponding country the receiver registered at the chamber of commerce
`Telephone`	Billing contact telephone number
`Email`	Email address the invoice is sent to
`Fax`	Billing contact fax number
`Type`	Relates to the account and specifies whether it is a reseller or an end-customer. Type 2 = Reseller Type 3 = End-customer

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
`AccountID`	Corresponding to the ID in the Cloud Platform
`CustomerNumber`	Can be used by the Partner for reference to own ERP system. This value is set in the Basic details of the customer in the Cloud Platform. This field is called External Customer ID
`CostCenter`	N/A
`CompanyName`	Company name of the customer
`Subscriptions`	Element that consists of 1 or more `Subscription` elements

Subscription element

The Subscription contains basic information about a customer's subscription as well as several PriceLine elements with detailed info.

Element	Description
`SubscriptionID`	Corresponds to the subscription in the Cloud platform
`SubscriptionName`	Name of the subscription
`BillingModel`	N/A
`PlanID`	Corresponding to the unique offer ID that the subscription is based on
`PlanName`	Corresponding to the name of the offer that the subscription is based on
`PlanCategoryName`	Corresponding to the name of the vendor that the subscription is based on
`StartDate`	Initial start date of the subscription
`SubscriptionPONumber`	PO Number of the subscription (can be filled in by the Reseller)
`PriceLines`	Element containing a collection of 1 or more `PriceLine` elements

PriceLine element

A PriceLine contains detailed information about its parent in this case of a Subscription. Below are the child elements of PriceLine further explained:

Element	Description
`LineId`	Identification number as stored in the Cloud platform
`UID`	Corresponding to the unique offer ID that the subscription is based on
`Description`	A combination of the vendor name and subscription name
`Quantity`	Amount of licenses/services purchased
`QuantityType`	Specifies the type of the Quantity (e.g. item)
`UnitPrice`	Purchase price of an individual license or service
`Discount`	The total discount of all included resources
`ExtendedPrice`	The total price of the licenses or services purchased
`VAT`	Amount of VAT applicable for the line item
`TaxZoneID`	Corresponds to the tax zone ID determined by Copaco. Based on country and offer.
`TaxPercentage`	Percentage applicable to the line item
`StartDate`	Start date of the subscription period
`EndDate`	End date of the subscription period
`Duration`	Duration of one subscription period (1, 3, etc), to be used in combination with `DurationType` value
`DurationType`	Duration type e.g. Month(s), Year(s)
`SKU`	N/A
`ConsumerCompanyNumber`	Unique internal ID corresponding to that in the Cloud platform
`ConsumerCompanyName`	Company name of the consumer
`SubPONumber`	PO Number at PriceLine level (currently same as on subscription level)
`RatePeriodId`	N/A

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. The Totals generally consist of:

Element	Description
`TotalExcludingVAT`	Total amount in Euro excluding VAT
`TotalVAT`	Total VAT in Euro, exclusive of telecommunication services
`TotalIncludingVAT`	Total amount in Euro including VAT