Get invoice line items for all the customers and latest billing period
    • 26 Oct 2024
    • 5 Minutes to read
    • Dark
      Light
    • PDF

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

    • Dark
      Light
    • PDF

    Article summary

    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

    Was this article helpful?