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"}
The filter criteria consist of three parts:
LeftFilter: The first filter construct, where you specify the field, value, and operator for the left side of the filter expression.
Field: Attribute to be used to filter. Value: Value of the attribute
For example, "LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} means that you want to filter invoices that have an invoice date on or after January 1, 2023.
RightFilter: The second filter construct, where you specify the field, value, and operator for the right side of the filter expression.
For example, "RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} means that you want to filter invoices that have an invoice date on or before December 31, 2023.
Operator: The logical operator that connects the left and right filters. You can use either "and" or "or" as the operator.
For example, "Operator": "and" means that you want to filter invoices that meet both the left and right filter criteria.
To use a single filter, just enter the field name, value, and operator. No need for the "LeftFilter" or "RightFilter" construct.
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"
}
}
Povratne informacije
Kmalu na voljo: V letu 2024 bomo ukinili storitev Težave v storitvi GitHub kot mehanizem za povratne informacije za vsebino in jo zamenjali z novim sistemom za povratne informacije. Za več informacij si oglejte: https://aka.ms/ContentUserFeedback.
Pošlji in prikaži povratne informacije za