Skip to main content

​
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.
ParameterTypeDescriptionDefault
billingStartDateStringFilter invoices issued on or after this date. Format: YYYY-MM-DD (e.g., 2024-01-05)None (all invoices)
billingEndDateStringFilter invoices issued on or before this date. Format: YYYY-MM-DD (e.g., 2024-12-12)None (all invoices)
pageIntegerPage number to retrieve (starts at 1)1
pageSizeIntegerNumber 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.0000,
    "tax": 0.0000,
    "total": 150.0000,
    "billingDate": "12-15-2024",
    "merchantLegalName": "Test Merchant",
    "merchantCustomerRefId": null,
    "customerFirstName": null,
    "customerLastName": null
  },
  // ... additional invoices
]

​
Response Main Fields

FieldTypeDescription
invoiceIdIntegerRevolv3’s unique identifier for this invoice
customerIdInteger | nullCustomer ID if linked to a customer record
merchantInvoiceRefIdString | nullYour internal invoice/order reference ID
binNumberStringFirst 6 digits of the payment method (identifies the bank)
last4DigitStringLast 4 digits of the payment method (safe to display)
invoiceStatusStringCurrent status: Paid, Pending, Noncollectable, Refund, etc.
subtotalNumberInvoice amount before tax
taxNumberTax amount
totalNumberTotal invoice amount (subtotal + tax)
billingDateStringDate the invoice was billed (format: MM-DD-YYYY)
merchantLegalNameStringYour merchant’s legal name
merchantCustomerRefIdString | nullYour internal customer reference ID
customerFirstNameString | nullCustomer’s first name (if available)
customerLastNameString | nullCustomer’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:
  1. Get invoices (you may need to paginate)
  2. Filter in your code by merchantInvoiceRefId
  3. 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:
  1. Use date filters to get the quarter’s invoices
  2. Paginate through all results
  3. Export to your accounting system

​
Best Practices

  1. Use date filters: Always filter by date range when possible to reduce response size
  2. Paginate large lists: Don’t try to get all invoices at once—use pagination
  3. Cache results: If you’re displaying invoices in a UI, cache the results
  4. Get details when needed: Use the list for overview, details endpoint for specifics
  5. 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