Get invoice line items for all the customers and latest billing period

URL

POST https://contoso-prod-api.azurewebsites.net/api/invoices/Download/v3/BillingPeriods/{billingperiodid}

{{billingperiodid}} – This is an optional parameter. Pass a value to this parameter to get the details for a particular billing period.

Request headers

Key	Value
Authorization	Bearer <access_token>
Content-Type	Application/json

Request body

Payload

Description

{

"TenantIds":"<tenantids-as-comma-separated-values>"

}

The body for this request is optional. If the body is left blank, the API would return the invoice line items for all the active customers.

Response body

An example response for the request to get active customers is as follows:

{
    "OperationType": null,
    "Status": "Success",
    "RequestCorrelationID": "37a20015-c6d1-443c-aeea-377b0e17f059",
    "ErrorMessage": null,
    "ErrorDetail": null,
    "Data": [
        {
            "CustomerBillingType": null,
            "ERPCustomerID": "409872RD",
            "CRMOpportunityID": "CRM-5544567"
            "CouponDiscountPercentage": null,
            "ProviderOfferId": "78991911-35A7-4320-92C9-DDE63C540A20",
            "SubscriptionEndDate": "2024-09-24T00:00:00",
            "ProviderCategory": null,
            "Category": "Custom",
            "ProductSKUId": "AF7D8CA4-4B47-49F8-9B0C-9F1F4651CAA2",
            "UniqueProviderOfferId": "78991911-35A7-4320-92C9-DDE63C540A20",
            "UnitPriceOfProduct": 6.00000000,
            "ReservationOrderId": null,
            "InvoiceEntity": "Customer",
            "ResellerName": null,
            "ProviderInvoiceNumber": "G012345678",
            "TenantID": "12hgyu80-434a-4c4a-n009-2cd1e1500b2d",
            "SubscriptionID": "60c29efd-434a-4c4a-a008-2cd1e1500b2d",
            "CurrencyCode": "USD",
            "AlternateId": null,
            "ItemCode": "",
            "CustomerName": "Contoso",
            "InvoiceNumber": "Invoice_Contoso_20241008_USD",
            "InvoiceGeneratedDate": "2024-10-08T00:00:00",
            "InvoiceDueDate": "2024-10-26T00:00:00",
            "SubscriptionName": "Microsoft 365 Business Essential",
            "ChargeStartDate": "2024-09-24T00:00:00",
            "ChargeEndDate": "2024-10-23T00:00:00",
            "LineItemType": "RenewalFee",
            "Quantity": 1.00000000,
            "UnitPrice": 6.00000000,
            "InvoiceLineAmount": 6.00000000,
            "DiscountAmount": null,
            "TaxAmount": 0.00000000,
            "PreTaxAmount": 6.00000000,
            "PostTaxAmount": 6.00000000,
            "TaxPercentage": 0.00000000,
            "SubscriptionType": "Custom",
            "OfferCode": "P-Custom",
            "TaxCode": null,
            "OfferID": "78991911-35A7-4320-92C9-DDE63C540A20",
            "InternalBillingID": "78349900",
            "CostOnPartner": 4.00000000,
            "PONumber": "6655",
            "Notes": "Customer is tax exempted, please do not apply any taxes while sending from Business Central",
            "OwnerEntity": "Customer",
            "OwnerName": "Contoso"
        },

Here is the explanation for the properties in the response (JSON)

Property

Description

OperationType

Can be ignored

Status

Indicates the status of the request. Possible values – Success / Error

RequestCorrelationID

Internal ID generated by C3 for correspondence for troubleshooting issues, if any.

ErrorMessage

Message in case the request runs into an error during processing

ErrorDetail

Additional detail related to the error in case there is an error while processing the request

Data

Contains a list of billing period objects represented by the following attributes:

Attribute	Description
CustomerBillingType	Customer billing Type - Custom value set by the Partner on the customer via Customer Configuration
ERPCustomerID	ERP Customer ID - Custom value set by the Partner on the customer via Customer Configuration
CRMOpportunityID	CRM Opportunity ID - Custom value set by the Partner on the customer via Customer Configuration
CouponDiscountPercentage	Discount %age value as Integer set by partner in coupon assigned to customer
ProviderOfferId	offer id of the product;Syntax : Market : Product ID : SKU ID : Term Duration : Billing Plan
SubscriptionEndDate	Subscription end date of any subscription
ProviderCategory	Category of an offer (refer to chart at last page) Possible Values are: OnlineServices AzurePlan PerpetualSoftware OnlineServicesNCE SoftwareSubscriptions Azure Custom Bundles
Category	Sub-Category of an offer(refer to chart at last page)
ProductSKUId	Unique identifier for an offer in MS ecosystem
UniqueProviderOfferId	Combined value of Provider Offer id and Provider Category to make it unique with syntax as: Market : Product ID : SKU ID : Term Duration : Billing Plan : ProviderCategory which is originated from Active Offers
UnitPriceOfProduct	Price per unit or license, as listed in the price list in supported currencies for applicable countries/regions.
ReservationOrderId	Order ID for Azure reservation or savings plan
InvoiceEntity	Entity the invoice is being issued to, possible values (Customer/Reseller)
ResellerName	Name of reseller (value is present only for invoices issued from Distributor to reseller else null)
ProviderInvoiceNumber	Microsoft Invoice number—a unique identifier for the invoice from Microsoft in partner center
TenantID	Microsoft Id of the customer
SubscriptionID	Subscription id for the offer
CurrencyCode	Currency in which the invoice is issued.
Alternateid	Alternate order ID provided by MS for Onetime billing data
Itemcode	Unique id for each product uploaded by partner to C3 system
CustomerName	Name of the customer
InvoiceNumber	A unique number to identify each invoice.
InvoiceGeneratedDate	Billing anniversary date on which your invoice is generated each month.
InvoiceDueDate	Due date for the invoice
SubscriptionName	Name of the subscription
ChargeStartDate	Date when billing starts for a specific billing period.
ChargeEndDate	Date when billing ends for a specific billing period. It depends on the charge cycle, billing plan, and coterminosity.
LineItemType	Enumeration that qualifies the line item whose possible values are : PurchaseFee, ProrateFee, RenewalFee, RefundAmount, UsageAmount, Adjustments, and newly added types from November-23 onwards. NCE line item charges removeQuantity NCE line item charges addQuantity NCE line item charges cancelImmediate NCE line item Refund NCE line item charges convert NCE line item charges new NCE line item charges renew NCE line item charges cycleCharge NCE line item charges moveQuantity
Quantity	Units bought. Use BillableQuantity for MS reconciliation
UnitPrice	Unit price of product
InvoiceLineAmount	Total amount for the line item (usually quantity x unit price)
DiscountAmount	Discount, if any, due to coupons
PreTaxAmount	The amount shown is prior to tax application.
TaxAmount	Tax amount to be applicable
PostTaxAmount	Line-item amount inclusive of applicable taxes.
TaxPercentage	% due to the tax rule
SubscriptionType	Earlier: License for license based and Azure for usage based subscriptions Now: We have returned the following values to represent categories with finer detail: OnlineServices – MS CSP License based products Custom – Partner offers Bundles - Bundles AzurePlan – Azure Plan Azure – Azure CSP subscriptions Note: We can switch it back to 1 and 0 as earlier if you recommend.
OfferCode	MS-CSPAzureUsage - for usage-based items. MS-CSPLicense - for license-based subscriptions, P-Custom - for custom offers.
TaxCode	Tax rule in effect
OfferID	Offer identifier associated with the subscription
InternalBillingID	Internal billing reference for the customer. This is set via Tenant Configuration option in the customer listing.
CostOnPartner	The amount charged to the partner. Note: The value is set on the first invoice line item per MS Offer ID.
PONumber	PO Number Note: This value is taken from Customer Configuration
Notes	Custom notes to be included on an invoice. The value is picked up from customer configuration, as set by the Partner, and set on the invoice. Changing the value in the customer configuration would not affect an already generated invoice.
OwnerEntity	Possible values: Customer / Site / Department Note : The value indicates the owning Entity for the invoice line item
OwnwerName	Name of the owner For Customer – It will be the name of the Customer For Site – It will be the name of the Site For Department – It will be the name of the Department

Error response

The API validates the input parameters – billing period id and the tenant Ids and returns 400 – Bad request error in case the input is found to be invalid.

A sample bad request error covering both the attributes is as follows:

{

    "OperationType": null,

    "Status": "Error",

"RequestCorrelationID": "3a0ce2d6-e8b6-402f-a926-10f5a7e0f2bb",

    "ErrorMessage": "ERROR_DESC_BAD_INPUT",

    "ErrorDetail": "ERROR_DESC_BAD_INPUT",

    "Data": [

        {

            "Atribute": "BillingPeriodId",

            "AtributeKey": "BILLING_PERIOD_ID",

            "Message": "Invalid Billing Period. Should be one of the 9 most recent billing periods",

            "DefaultMessage": "INVALID_BILLING_PERIOD_ID",

            "Value": "2323

    ]

}

The following table explains the constituents of the response in detail:

Property	Description
OperationType	Can be ignored
Status	Indicates the status of the request. Possible values – Success / Error
RequestCorrelationID	Internal ID generated by C3 for correspondence for troubleshooting issues, if any.
ErrorMessage	Message in case the request runs into an error during processing
ErrorDetail	Additional detail related to the error in case there is an error while processing the request
Data	Contains a list of validation errors represented by the following attributes: Attribute – The input in the request that is invalid AttributeKey – This is for internal purposes (only used if we were to present custom labels to the user) Message –Reason for the validation failure DefaultMessage – error message in English Value – input