Get a collection of invoices
Applies to: Partner Center | Partner Center operated by 21Vianet | Partner Center for Microsoft Cloud for US Government
How to retrieve a collection of the partner's invoices.
Prerequisites
- Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.
C#
To get a collection of all available invoices, use the Invoices property to get an interface to invoice operations, and then call the Get or GetAsync method to retrieve the collection.
To get a paged collection of invoices, first call the BuildIndexedQuery method and pass it the page size to create an IQuery object. Next, use the Invoices property to get an interface to invoice operations, and then pass the IQuery object to the Query or QueryAsync method to send the request and get the first page.
Next, use the Enumerators property to get an interface to the collection of supported resource collection enumerators, and then call Invoices.Create to create an enumerator for traversing the collection of invoices. Finally, use the enumerator to retrieve and work with each page of invoices as shown in the following code example. Each call to the Next method sends a request for the next page of invoices based on the page size.
// IAggregatePartner partnerOperations;
// int invoicePageSize;
// Is this an unpaged or paged request?
bool isUnpaged = (this.invoicePageSize <= 0);
// If the scenario is unpaged, get all the invoices, otherwise get the first page.
var invoicesPage = (isUnpaged)
? partnerOperations.Invoices.Get()
: partnerOperations.Invoices.Query(QueryFactory.Instance.BuildIndexedQuery(this.invoicePageSize));
// Create an invoice enumerator for traversing the invoice pages.
var invoicesEnumerator = partnerOperations.Enumerators.Invoices.Create(invoicesPage);
int lineCounter = 1;
while (invoicesEnumerator.HasValue)
{
// Print the current invoice results page.
var invoices = invoicesEnumerator.Current.Items;
foreach (var i in invoices)
{
Console.WriteLine(String.Format("{0,3}. {1} {2} {3,16:C2}",
lineCounter++,
i.Id,
i.InvoiceDate.ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'"),
i.TotalCharges));
}
Console.WriteLine();
Console.Write("Press any key to retrieve the next invoices page");
Console.ReadKey();
// Get the next page of invoices.
invoicesEnumerator.Next();
}
For a slightly different example, see Sample: Console test app. Project: Partner Center SDK Samples Class: GetPagedInvoices.cs
Note
The same API is used for all modern commercial purchases as well as 145p and Office licenses. Size and offset are only considered for legacy invoices. For all modern commercial purchases, pagesize & offset will be ignored.
REST request
Request syntax
| Method | Request URI |
|---|---|
| GET | {baseURL}/v1/invoices?size={size}&offset={offset} HTTP/1.1 |
| GET | {baseURL}/v1/invoices?size={size}&offset={offset}&filter={"LeftFilter":{"Field":{field},"Value":{value},"Operator":{operator}},"RightFilter":{"Field":{field},"Value":{value},"Operator":{operator}},"Operator":{operator}} HTTP/1.1 |
URI parameters
Use the following query parameters when creating the request.
| Name | Type | Required | Description |
|---|---|---|---|
| size | int | No | The number of invoice resources to return in the response. This parameter is optional. |
| offset | int | No | The zero-based index of the first invoice to return. |
| filter | string | No | Text-based custom filter criteria to reduce the invoice resources in the response. Use this condition to prevent timeout error. See how to use the filter condition |
How to use the filter condition
An example of the filter condition:
/v1/invoices?size=10&offset=0&filter={"LeftFilter":{"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"},"RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"},"Operator":"and"}
To filter your data effectively, understand the three main components of the filter criteria:
LeftFilter: Specify the field, value, and operator for the left side of the filter expression to set the initial condition.
Field: Attribute to be used to filter Value: Value of the attribute
Example, "LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} filters invoices on or after January 1, 2023.
RightFilter: Define the field, value, and operator for the right side of the filter expression to complete the condition.
Example, "RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} filters invoices on or before December 31, 2023.
Operator: Connect the left and right filters with a logical operator. Use either "and" or "or" to combine the criteria.
Example, "Operator": "and" ensures the filter includes invoices that meet both conditions.
For a single filter, enter the field name, value, and operator without needing the "LeftFilter" or "RightFilter" constructs.
This approach helps you filter your data precisely and efficiently.
Request headers
For more information, see Partner Center REST headers.
Request body
None
Request example
GET https://api.partnercenter.microsoft.com/v1/invoices?size=200&offset=0 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: e88d014d-ab70-41de-90a0-f7fd1797267d
MS-CorrelationId: de894e18-f027-4ac0-8b5a-34f0c222af0c
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com
Important
As of June 2023, the latest Partner Center .NET SDK release 3.4.0 is now archived. You can download the SDK release from GitHub, along with a readme file that contains useful information.
Partners are encouraged to continue to use the Partner Center REST APIs.
REST response
If successful, the response body contains the collection of Invoice resources.
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and other debugging information. Use a network trace tool to read this code, error type, and other parameters. For the full list, see Partner Center REST error codes.
Response example
HTTP/1.1 200 OK
Content-Length: 256
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 57eb2ca7-755f-450f-9187-eae1e75a0114
MS-RequestId: a45e6643-1caf-4429-8f90-07c03d85bc2b
Date: Thu, 24 Mar 2016 05:21:01 GMT
{
"totalCount": 2,
"items": [
{
"id": "D02005YFHI",
"invoiceDate": "2017-01-21T00:00:00Z",
"totalCharges": 24606.35,
"paidAmount": 1000,
"currencyCode": "GBP",
"currencySymbol": "£",
"pdfDownloadLink": "/invoices/D02005YFHI/documents/statement",
"taxReceipts": [
{
"id": "123456",
"taxReceiptPdfDownloadLink": "/invoices/D02005YFHI/receipts/123456/documents/statement"
}
],
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "office",
"links": {
"self": {
"uri": "/invoices/Recurring-D02005YFHI/lineitems/Office/BillingLineItems",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"documentType": "invoice",
"invoiceType": "Recurring",
"links": {
"self": {
"uri": "/invoices/Recurring-D02005YFHI",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Invoice"
}
},
{
"id": "G000024130",
"invoiceDate": "2018-02-08T01:22:47.603895Z",
"totalCharges": 586366,
"paidAmount": 0,
"currencyCode": "CHF",
"currencySymbol": "CHF",
"pdfDownloadLink": "/invoices/G000024130/documents/statement",
"taxReceipts": [
{
"id": "234567",
"taxReceiptPdfDownloadLink": "/invoices/G000024130/receipts/234567/documents/statement"
}
],
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "one_time",
"links": {
"self": {
"uri": "/invoices/OneTime-G000024130/lineitems/OneTime/BillingLineItems",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"amendments": [
{
"id": "G000024131",
"invoiceDate": "2018-02-08T18:44:37.5381456Z",
"totalCharges": 107661.12,
"paidAmount": 0,
"currencyCode": "CHF",
"currencySymbol": "CHF",
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "one_time",
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"documentType": "adjustment_note",
"amendsOf": "G000024130",
"invoiceType": "OneTime",
"attributes": {
"objectType": "Invoice"
}
}
],
"documentType": "void_note",
"invoiceType": "OneTime",
"links": {
"self": {
"uri": "/invoices/OneTime-G000024130",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Invoice"
}
}
],
"links": {
"self": {
"uri": "/invoices?size=2&offset=0",
"method": "GET",
"headers": []
},
"next": {
"uri": "/invoices?size=2&offset=2",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Collection"
}
}