Billing APIs

Endpoints

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 for this is: /api/v1/invoices

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

The endpoint for this is: /api/v1/example-invoices

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 for this is: /api/v1/customer-specifications

All endpoints 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.

Billing API Endpoints

All above endpoints have the same output.

Example (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": ......
                                "PurchaseDiscount": "......",
                                "PurchasePrice": ......,
                                "PurchaseVAT": ......,
                                "SalesDiscount": "......",
                                "SalesPrice": ......,
                                "SalesVAT": ......,
                                "InvoiceRowHash": "......",
                                }
                            ],
                        "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
`Customers`	An `Invoice` normally has a `Customers` child element. This contains 1 or more `Customer` elements.
`Subscriptions`	The `Subscriptions` element contains basic information about a customer's subscription as well as a `PriceLine` element with detailed info.
`PriceLines`	The `PriceLines` element contains detailed information about its parent in this case of a Subscription.
`Header`	The `Header` element contains basic information about the `Invoice`.
`Receiver`	The `Receiver` element contains info about the receiving Partner.
`Sender`	The `Sender` element has information about the Sending partner.
`Totals`	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`.

Customers element

Field	Data type	Description
AccountID	string	Corresponding to the ID in the Cloud Platform
CompanyName	string	Company name of the customer
CostCenter	string	N/A
CustomerNumber	string	Can be used by the Partner for reference to their 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
Subscriptions	array(Subscriptions)	Element that consists of 1 or more `Subscriptions` elements

Subscriptions element

Field	Data type	Description
BillingModel	int	Value is always returned as “0“
PlanCategoryName	string	Corresponding to the name of the vendor that the subscription is based on
PlanID	string	Corresponding to the unique offer ID that the subscription is based on
PlanName	string	Corresponding to the name of the offer that the subscription is based on
PriceLines	array(PriceLine)	Element containing a collection of 1 or more `PriceLine` elements
StartDate	string	Initial start date of the subscription
SubscriptionID	string	Corresponds to the subscription in the Cloud platform
SubscriptionName	string	Name of the subscription
SubscriptionPONumber	string	PO Number of the subscription (can be filled in by the Reseller)

PriceLines element

Field	Data type	Description
ConsumerCompanyName	string	Company name of the consumer
ConsumerCompanyNumber	string	Unique internal ID corresponding to that in the Cloud platform
Description	string	A combination of the vendor name and subscription name
Discount	int, decimal or double	Fixed value of always “0“
Duration	string	Duration of one subscription period (1, 3, etc), to be used in combination with `DurationType` value
DurationType	string	Duration type e.g. Month(s), Year(s)
BillingFrequency	string	Returns the billing frequency of a subscription e.g. "" (empty), Monthly, Yearly, One Time
EndDate	string	End date of the subscription period
ExtendedPrice	int, decimal or double	The total price of the licenses or services purchased
LineId	string	Identification number as stored in the Cloud platform
Quantity	int, decimal or double	Amount of licenses/services purchased
QuantityType	string	Value is always “item”
RatePeriodId	int	Value is always 0
SKU	string	Value is always ““ (empty) as SKUs are not supported in the Copaco Cloud platform.
StartDate	string	Start date of the subscription period
SubPONumber	string	PO Number at PriceLine level (currently same as on subscription level)
TaxPercentage	decimal	Percentage applicable to the line item
TaxZoneID	string	Corresponds to the tax zone ID determined by Copaco. Based on country and offer.
UID	string	Corresponding to the unique offer ID that the subscription is based on
UnitPrice	decimal	Purchase price of an individual license or service
VAT	decimal	Amount of VAT applicable for the line item
PurchaseDiscount	string	Amount of discount on the Purchase Price
PurchasePrice		The in-price for the reseller
PurchaseVAT		Amount of VAT applicable for the purchase item
SalesDiscount	string	Amount of discount on the Sales Price
SalesPrice		The retail price for the reseller to the customer
SalesVAT		Amount of VAT applicable for the sales item
InvoiceRowHash	string	Unique generated value that matches the invoice to link two lines to match the purchase and sales price

Header element

Field	Data type	Description
Currency	string	Currency, like `EUR`
Date	string	Invoice date
Description	string	Invoice description, always contains the value “Invoice“
ExpirationDate	string	Due date of the invoice
InvoiceID	string	The identifying number of the invoice
Language	string	The language used by Copaco to create the printed version of the invoice
LanguageCode	string	Language code used by Copaco to create the printed version of the invoice
TermsOfPaymentDays	int	Terms of payment days agreed upon
Type	string	Always contains the value “INVOICE”
TypeIdentifier	int	Code corresponding to the type

Receiver element

Field	Data type	Description
AccountID	string	Receiver Account ID corresponding to that in the Cloud Platform
Address	string	Street the receiver is registered at the chamber of commerce
City	string	City the receiver is registered at the chamber of commerce
CompanyName	string	Company name of the receiver
ContactFirstName	string	Billing contact first name
ContactLastName	string	Billing contact last name
ContactMiddleName	string	Billing contact middle name (Always ““)
Country	string	Corresponding country the receiver registered at the chamber of commerce
CountryCode	string	Specific code for the country of the receiver
CustomerNumber	string	Corresponds with the Copaco customer account number. (This is the External Customer ID configured in the Cloud Platform)
Email	string	Email address the invoice is sent to
Fax	string	Billing contact fax number (Always ““)
Telephone	string	Billing contact telephone number
Type	int	Relates to the account and specifies whether it is a reseller or an end-customer. Type 2 = Reseller Type 3 = End-customer
VATNumber	string	VAT number of the receiver
Zip	string	Zip code the receiver is registered at the chamber of commerce

Sender element

Field	Data type	Description
AccountID	string	Sender Account ID as shown in the Cloud Platform
Address	string	Street the sender is registered at the chamber of commerce
BankAccount	string	Number of sender's Bank account
BIC	string	Bank Identifier Code of the sender's bank account
ChamberOfCommerce	string	Number of the sender as registered in the Chamber of Commerce
City	string	City the sender is registered in the Chamber of Commerce
CompanyName	string	Company name of the sender
Country	string	Country the sender is registered at the chamber of commerce
CountryCode	string	Specific code for the country of the sender
Fax	string	Sender contact fax number (Always ““)
IBAN	string	IBAN Number of the sender
Logo	string	Publicly accessible URL to your company logo, to place the company logo on the print version of the invoice (Always ““)
PostalCode	string	Postal code of the sender
Telephone	string	Sender contact telephone number
VATNumber	string	VAT number of the sender
Website	string	Sender's website (Always ““)

Totals element

Field	Data type	Description
TotalExcludingVAT	decimal	Total amount in Euro excluding VAT
TotalIncludingVAT	decimal	Total amount in Euro including VAT
TotalVAT	decimal	Total VAT in Euro, exclusive of telecommunication services