Get Invoices API

What is the Get Invoices API?

The Get Invoices API retrieves a list of invoices from your account. Use it to:

View all your invoices
Filter invoices by date, status, or other criteria
Paginate through large lists of invoices
Get a summary of invoice information

When to use it:

Building a dashboard or reporting system
Reconciling payments with your accounting system
Looking up invoices for customer support
Generating reports or exports
Monitoring payment activity

Note: This endpoint returns summary information. For detailed invoice information including payment attempts, use Get Invoice Details.

API Endpoint

GET {{Api Root}}/api/Invoices/v1

Replace {{Api Root}} with:

Production: api.revolv3.com
Sandbox: api-sandbox.revolv3.com

Request Parameters

All parameters are optional. Use these main parameters to filter or paginate the results.

Parameter	Type	Description	Default
`billingStartDate`	String	Filter invoices issued on or after this date. Format: `YYYY-MM-DD` (e.g., `2024-01-05`)	None (all invoices)
`billingEndDate`	String	Filter invoices issued on or before this date. Format: `YYYY-MM-DD` (e.g., `2024-12-12`)	None (all invoices)
`page`	Integer	Page number to retrieve (starts at 1)	1
`pageSize`	Integer	Number of invoices per page (maximum: 100)	100

Understanding Date Filters

Date format: Use YYYY-MM-DD format (e.g., 2024-01-05)
Time zone: Dates are based on billingDate in UTC
Inclusive: BillingStartDate and BillingEndDate are inclusive (invoices on those dates are included)

Understanding Pagination

Page numbers: Start at 1 (not 0)
Page size: Maximum 100 invoices per page
Default: 100 invoices per page if not specified
Total pages: Calculate based on total invoices and page size

Example Requests

Get All Invoices (First Page)

GET {{Api Root}}/api/Invoices/v1

Returns the first 100 invoices (default page size).

Filter by Date Range

GET {{Api Root}}/api/Invoices?startDate=2024-01-05&endDate=2024-12-12

Returns invoices between January 5, 2024 and December 12, 2024.

Paginated Request

GET {{Api Root}}/api/Invoices?startDate=2024-01-05&endDate=2024-12-12&page=2&pageSize=10

Returns page 2 with 10 invoices per page, filtered by date range.

Response Format

The API returns a JSON array of invoice objects. Each object contains summary information about the invoice.

Sample Response

[
  {
    "InvoiceId": 388815,
    "CustomerId": null,
    "MerchantInvoiceRefId": "1234-5678-9101",
    "BinNumber": "444433",
    "Last4Digit": "1111",
    "InvoiceStatus": "Paid",
    "Subtotal": 150.0,
    "Tax": 0.0,
    "Total": 150.0,
    "BillingDate": "12-15-2024",
    "MerchantLegalName": "Test Merchant",
    "MerchantCustomerRefId": null,
    "CustomerFirstName": null,
    "CustomerLastName": null
  }
]

This example shows a single invoice object; in real responses, the array can contain multiple invoices.

Response Main Fields

Field	Type	Description
`invoiceId`	Integer	Revolv3’s unique identifier for this invoice
`customerId`	Integer \| null	Customer ID if linked to a customer record
`merchantInvoiceRefId`	String \| null	Your internal invoice/order reference ID
`binNumber`	String	First 6 digits of the payment method (identifies the bank)
`last4Digit`	String	Last 4 digits of the payment method (safe to display)
`invoiceStatus`	String	Current status: `Paid`, `Pending`, `Noncollectable`, `Refund`, etc.
`subtotal`	Number	Invoice amount before tax
`tax`	Number	Tax amount
`total`	Number	Total invoice amount (subtotal + tax)
`billingDate`	String	Date the invoice was billed (format: MM-DD-YYYY)
`merchantLegalName`	String	Your merchant’s legal name
`merchantCustomerRefId`	String \| null	Your internal customer reference ID
`customerFirstName`	String \| null	Customer’s first name (if available)
`customerLastName`	String \| null	Customer’s last name (if available)

Sorting

Results could be automatically sorted by: BillingDate, LastUpdateDate, InvoiceId

Getting Detailed Invoice Information

This endpoint returns summary information. For detailed information including:

Payment attempts (all tries, not just the latest)
Full payment method details
Invoice line items
Processor responses

Use the Get Invoice Details endpoint:

GET {{Api Root}}/api/Invoices/{invoiceId}

Replace {invoiceId} with the invoice ID from the list response.

Real-World Use Cases

Use Case 1: Dashboard Display

Scenario: Show recent invoices on a dashboard Solution:

GET {{Api Root}}/api/Invoices/v1?page=1&pageSize=10

Returns the 10 most recent invoices (sorted by date, newest first).

Use Case 2: Monthly Reconciliation

Scenario: Get all paid invoices for a specific month Solution:

GET {{Api Root}}/api/Invoices?startDate=2024-01-01&endDate=2024-01-31

Use Case 3: Customer Support Lookup

Scenario: Find an invoice by customer’s order ID Solution:

Get invoices (you may need to paginate)
Filter in your code by merchantInvoiceRefId
Or use the invoice details endpoint if you have the invoice ID

Use Case 4: Export for Accounting

Scenario: Export all invoices for a quarter Solution:

Use date filters to get the quarter’s invoices
Paginate through all results
Export to your accounting system

Best Practices

Use date filters: Always filter by date range when possible to reduce response size
Paginate large lists: Don’t try to get all invoices at once—use pagination
Cache results: If you’re displaying invoices in a UI, cache the results
Get details when needed: Use the list for overview, details endpoint for specifics
Handle empty results: Your code should handle cases where no invoices match filters

Common Questions

Q: How do I get all invoices? A: Don’t specify any filters, but use pagination to get them in chunks. The default page size is 100. Q: What’s the maximum page size? A: 100 invoices per page. Use this for bulk operations, but smaller pages (25-50) are better for UI display. Q: How do I know if there are more pages? A: If you get a full page (e.g., 25 invoices when pageSize=25), there might be more. Request the next page to check.

Next Steps

Get Invoice Details — Get detailed information about a specific invoice
Invoice Status — Understand what each invoice status means
Invoice Export — Export invoices to CSV for reporting

Getting Started

Authentication & Security

Core Concepts & Data Models

Integration Flows

Plugins

API Reference

Webhooks & Event Handling

Error Codes & Troubleshooting

Testing & Sandbox

Certification & Go-Live Checklist

Appendix / Glossary

FAQ

What is the Get Invoices API?

API Endpoint

Request Parameters

Understanding Date Filters

Example Requests

Get All Invoices (First Page)

Filter by Date Range

Paginated Request

Response Format

Sample Response

Response Main Fields

Sorting

Getting Detailed Invoice Information

Real-World Use Cases

Use Case 1: Dashboard Display

Use Case 2: Monthly Reconciliation

Use Case 3: Customer Support Lookup

Use Case 4: Export for Accounting

Best Practices

Common Questions

Next Steps

​What is the Get Invoices API?

​API Endpoint

​Request Parameters

​Understanding Date Filters

​Understanding Pagination

​Example Requests

​Get All Invoices (First Page)

​Filter by Date Range

​Paginated Request

​Response Format

​Sample Response

​Response Main Fields

​Sorting

​Getting Detailed Invoice Information

​Real-World Use Cases

​Use Case 1: Dashboard Display

​Use Case 2: Monthly Reconciliation

​Use Case 3: Customer Support Lookup

​Use Case 4: Export for Accounting

​Best Practices

​Common Questions

​Next Steps

What is the Get Invoices API?

API Endpoint

Request Parameters

Understanding Date Filters

Understanding Pagination

Example Requests

Get All Invoices (First Page)

Filter by Date Range

Paginated Request

Response Format

Sample Response

Response Main Fields

Sorting

Getting Detailed Invoice Information

Real-World Use Cases

Use Case 1: Dashboard Display

Use Case 2: Monthly Reconciliation

Use Case 3: Customer Support Lookup

Use Case 4: Export for Accounting

Best Practices

Common Questions

Next Steps