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

20 Dec 2023
4 Minutes to read

Print
Share
Dark
Light
PDF

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

Updated on 20 Dec 2023
4 Minutes to read

Print
Share
Dark
Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

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": "2f2029ca-54d5-45b8-8e3c-498ff5b6c8f8",

    "ErrorMessage": null,

    "ErrorDetail": null,

    "Data": [

        {

            "CustomerBillingType": null,

            "ERPCustomerID": null,

            "CRMOpportunityID": null,

            "CouponDiscountPercentage": null,

            "ProviderOfferId": null,

            "SubscriptionEndDate": null,

            "ProviderCategory": null,

            "Category": "OneTime",

            "ProductSKUId": null,

            "TenantID": "d6bc65d1-5678-4eec-1234-5cd9a16ddf66",

            "SubscriptionID": "b56a8f1a-1234-a06f-6d4b-057706b11523",

            "CurrencyCode": "USD",

            "AlternateId": "df5f0cda6324",

            "ItemCode": null,

            "CustomerName": "Contoso",

            "InvoiceNumber": "Invoice_ Contoso_20221218_USD",

            "InvoiceGeneratedDate": "2022-12-18T00:00:00",

            "InvoiceDueDate": "2023-01-14T00:00:00",

            "SubscriptionName": "Twilio SendGrid",

            "ChargeStartDate": "2022-11-02T00:00:00",

            "ChargeEndDate": "2022-12-01T00:00:00",

            "LineItemType": "OneTimeCharges",

            "Quantity": 1.00000000,

            "UnitPrice": 0.00000000,

            "InvoiceLineAmount": 0.00000000,

            "DiscountAmount": null,

            "TaxAmount": 0.00000000,

            "PreTaxAmount": 0.00000000,

            "PostTaxAmount": 0.00000000,

            "TaxPercentage": 0.00000000,

            "SubscriptionType": "OneTime",

            "OfferCode": "MS-CSPLicense",

            "TaxCode": null,

            "OfferID": "DZH318Z09HH9",

            "InternalBillingID": "000670",

            "CostOnPartner": 0.00000000,

            "PONumber": "",

            "Notes": null,

            "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
TenantID	Microsoft Id of the customer
SubscriptionID	Subscription id for the offer
CurrencyCode	Invoice currency
Alternateid	Id provided by MS for Onetime billing data
Itemcode
CustomerName	Name of the customer
InvoiceNumber	Invoice number
InvoiceGeneratedDate	Date when the invoice is generated
InvoiceDueDate	Due date for the invoice
SubscriptionName	Name of the subscription
ChargeStartDate	Start date of the charge period for the subscription
ChargeEndDate	End date of the charge period for the subscription
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	Quantity considered for the line item
UnitPrice	Unit price
InvoiceLineAmount	Total amount for the line item (usually quantity x unit price)
DiscountAmount	Discount, if any, due to coupons
PreTaxAmount	This is the amount before applying Tax
TaxAmount	Tax amount
PostTaxAmount	Line item amount after applying 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

Was this article helpful?

What's Next

Get Azure Consumption Report

Table of contents

URL
Request headers
Request body
Response body
Error response