Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Transactions > Get invoices

Get invoices

Retrieves invoices for a specified account. 

Invoices are returned in reverse chronological order by updatedDate.

Request

  • API Sandbox: GET https://apisandbox-api.zuora.com/rest/v1/transactions/invoices/accounts/{account-key}
  • Production: GET https://api.zuora.com/rest/v1/transactions/invoices/accounts/{account-key}

Request Parameters

account-key

required

path

Account number or account ID

pageSize

optional

query

Number of rows to return.  Maximum is 40; default is 20.

Response Parameters

success

Contains true if successful, otherwise false.

processId

Internal process ID to assist Zuora support. Only returned if success is false.

reasons

Information on one or more reasons for the result. Only returned if success is false.

code

Eight-digit numeric error code

message

Description of the error

Invoices

Contains information about one or more invoices:

Id

Invoice ID

accountId

Customer account ID

accountNumber

Customer account number

accountName

Customer account name

invoiceDate

Invoice date as yyyy-mm-dd

invoiceNumber

Unique invoice ID, returned as a string

dueDate

Payment due date as yyyy-mm-dd

invoiceTargetDate

Date through which charges on this invoice are calculated, as yyyy-mm-dd

amount

Amount of the invoice before adjustments, discounts, and similar items

balance

Balance remaining due on the invoice (after adjustments, discounts, etc.)

createdBy

User ID of the person who created the invoice. If a bill run generated the invoice, then this is the user ID of person who created the bill run.

status

Status of the invoice in the system - not the payment status, but the status of the invoice itself. Possible values are: PostedDraftCanceledError.

body The REST URL of the invoice PDF file.

cf_txtn__c

One or more custom fields

cf_pkn__c

One or more custom fields

invoiceItems

 

Information on one or more items on this invoice:

id

Item ID

subscriptionName

Name of the subscription for this item

subscriptionId

ID of the subscription for this item

serviceStartDate

Start date of the service period for this item, as yyyy-mm-dd. For a one-time fee item, the date of the charge.

serviceEndDate

End date of the service period for this item, i.e., the last day of the service period, as yyyy-mm-dd

chargeAmount

The amount of the charge. This amount doesn't include taxes regardless if the charge's tax mode is inclusive or exclusive.

chargeDescription

Description of the charge

chargeName

Name of the charge

chargeId

ID of the charge

productName

Name of the product associated with this item

quantity

Quantity of this item, in the configured unit of measure for the charge

taxAmount

Tax applied to the charge

unitOfMeasure

Unit used to measure consumption, as configured in the web-based UI at Z-Billing > Settings

chargeDate

The date and time when the invoice item is created.

chargeType

The type of the charge. Possible values are:
  • OneTime
  • Recurring
  • Usage

processingType

The processing type of the invoice item. Possible values are:
  • Charge
  • Discount
  • Prepayment
  • Tax

cf_txtn__c

One or more custom fields

cf_pkn__c

One or more custom fields

InvoiceFiles

Information about the invoice PDF file:

id ID of the invoice PDF file.
This is the ID for the file object and different from the file handle id in the pdfFileUrl field. To open a file, you need to use the file handle ID.
versionNumber Version number of the invoice PDF file
pdfFileUrl REST URL for the invoice PDF file. Click the URL to open the invoice PDF file.

nextPage

URL for requesting the next page of the response, if it exists; otherwise absent

Examples

HTTP request:

GET https://api.zuora.com/rest/v1/transactions/invoices/accounts/A00000002

CURL request:

##
## Query Invoices
##
echo
echo "=============Get Invoices by Account Key============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Accept:application/json" -X GET $BASE_URL/v1/transactions/invoices/accounts/A00000002

JSON response:

{
  "invoices": [
    {
      "id": "2c92c095511f5b4401512682dcfd7987",
      "accountId": "2c92c0f8511f4b9d01512680ab282370",
      "accountNumber": "A00000002",
      "accountName": "XYZ, Inc",
      "invoiceDate": "2016-11-10",
      "invoiceNumber": "INV00000002",
      "dueDate": "2016-12-10",
      "invoiceTargetDate": "2016-11-10",
      "amount": 21.1,
      "balance": 21.1,
      "createdBy": "2c92c0f84fbac224014fc55639fe11d4",
      "status": "Draft",
      "body": null,
      "invoiceItems": [
        {
          "id": "2c92c095511f5b4401512682dd017989",
          "subscriptionName": "A-S00000004",
          "subscriptionId": "2c92c0f9511f56b2015126814ad532cc",
          "serviceStartDate": "2016-11-10",
          "serviceEndDate": "2016-11-30",
          "chargeAmount": 21.1,
          "chargeDescription": "",
          "chargeName": "Annual Fee",
          "chargeId": "2c92c0f9511f56b2015126814af832d2",
          "productName": "TeamCollab Enterprise",
          "quantity": 1,
          "taxAmount": 0,
          "unitOfMeasure": "",
          "chargeDate": "2016-11-20 17:47:00",
          "chargeType": "OneTime",
          ​​​​​​​"processingType": "Charge"
        }
      ],
      "invoiceFiles": []
    }
  ],
  "success": true
}
Last modified
21:58, 10 Nov 2016

Tags

Classifications

(not set)