Pagination

All list endpoints return results in reverse chronological order - newest createdAt first - and use cursor-based pagination. Unlike offset pagination, cursor pagination stays stable as new records are created between requests: you never see duplicates or skip items mid-page.

Response envelope

Every list response wraps its results in the following shape:

{
  "data": [ /* resource objects */ ],
  "hasMore": true
}

data - the array of resource objects for the current page.
hasMore - true if there are more records beyond this page; false when you have reached the end.

Pagination parameters

Control page size and position with these query parameters:

Parameter	Description
`limit`	Number of results to return. Accepts `1`-`50`. Defaults to `50`.
`startingAfter=<id>`	Return the page of results that comes after the given resource ID, moving forward through older records.
`endingBefore=<id>`	Return the page of results that comes before the given resource ID, moving backward toward newer records.

startingAfter and endingBefore are mutually exclusive. Supplying both in the same request returns a 400 Bad Request.

Walking forward through pages

To iterate through all records, start with your desired limit, check hasMore, and use the last item’s ID as startingAfter on the next request. Repeat until hasMore is false.

### Page 1 - first request, no cursor
GET /v2/payments?limit=25 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

### Response: data[24].id = "pay_last_on_page_1", hasMore = true

### Page 2 - pass the last ID from page 1
GET /v2/payments?limit=25&startingAfter=pay_last_on_page_1 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

### Response: data[24].id = "pay_last_on_page_2", hasMore = true

### Page 3 - pass the last ID from page 2
GET /v2/payments?limit=25&startingAfter=pay_last_on_page_2 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

### Response: hasMore = false - you have reached the last page

Filtering

Each list endpoint exposes its own filter parameters. The following filters are available across most endpoints:

Parameter	Description
`externalId`	Look up resources by your own identifier instead of the Melio-assigned ID.
`created[gte]`	Return only records created at or after this RFC 3339 date-time (e.g., `2024-01-01T00:00:00Z`).
`created[lte]`	Return only records created at or before this RFC 3339 date-time.
`metadata[key]=value`	Match resources where the given metadata key equals the given value. Supply multiple `metadata[key]` parameters to require all of them (AND logic).

The payments list endpoint also supports these additional filters:

Parameter	Description
`status`	Filter by payment status: `scheduled`, `in-progress`, `completed`, `failed`, or `canceled`.
`originatingAccountId`	Return only payments funded from this internal account ID.
`receivingAccountId`	Return only payments delivered to this external account ID.

Example - find all completed payments for an invoice:

GET /v2/payments?status=completed&metadata[invoiceId]=INV-00123 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

Sorting

The sort order is fixed: results always come back newest-first by createdAt. There is no sortBy parameter.

All filters combine with AND logic - every filter you supply must match for a record to appear. Filters also compose cleanly with pagination: once you have a filtered result set, use startingAfter and endingBefore exactly as you would on an unfiltered list to walk through its pages.

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Response envelope

Walking forward through pages

Filtering

Sorting

​Response envelope

​Pagination parameters

​Walking forward through pages

​Filtering

​Sorting

Response envelope

Pagination parameters

Walking forward through pages

Filtering

Sorting