Search API
Search orders, transactions, merchants, projects, users, payment links, API calls and webhooks with Lucene queries.
The Search API finds objects on your platform with a query: orders and transactions, merchants and projects, users, payment links, and the logs of API calls and webhooks. The Admin portal and the Merchant portal use it for their lists and search boxes. Use it for support, reporting and exports. To follow every change to orders, use the Stream API instead.
Paths and authentication
Each object has its own endpoint. Send a POST with the query in a JSON body. There are two variants of each path:
| Path | Searches |
|---|---|
/ | All merchants of your platform. For admins: an admin user's token. Ask your Ginger contact whether your admin API key works here too. |
/ | Only the objects of your own merchant, and of the projects your account may access. For merchant users and API keys. |
The account needs permission for POST on the path. See Authentication and Permissions.
| Object | Path | Results in |
|---|---|---|
| Orders | .../ | orders |
| Transactions | .../ | transactions |
| Merchants | .../ | merchants. Admins only: / returns 403 Forbidden. |
| Projects | .../ | projects, with the fields of their merchant |
| Users | .../ | users |
| Payment links | .../ | payment_ |
| API calls | .../ | apicalls, the log of requests to the API |
| Webhooks | .../ | webhook_, the log of webhook calls to merchants |
Search
curl https://api.example.com/v1/admin/search/orders/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"query": "status:completed AND currency:EUR",
"size": 20,
"sort": "created desc"
}'{
"hits": 1250,
"orders": [
{
"id": "738709ef-d555-4720-9e49-05b1c7f14657",
"status": "completed",
"t_payment_method": "credit-card"
}
]
}The response is shortened. hits is the number of matches, the list holds one page of them. Page with start and
size, or for orders and transactions with search_. See
Search orders in the API reference for all fields.
Add ?format=csv to the path of orders or transactions to get the results as CSV instead of JSON.
Query syntax
The query uses the Lucene query syntax. Some examples:
| Query | Finds |
|---|---|
* | Everything |
fdd81581-28b0-42fc-8be7-9228762d9368 | Objects with this value in any field, such as an ID |
status:completed | Objects with this value in the status field |
status:completed currency:EUR | Both: terms without an operator must all match |
status:(error OR cancelled) | Either value |
created:["2026-10-01T00:00:00Z" TO "2026-10-31T23:59:59Z"] | A range |
* -request_ | Everything except GET requests, in the API call log |
request_ | A wildcard |
Terms without an operator are combined with AND: every term must match. A query with a syntax error is refused.
Build queries with a library rather than by hand, so values with special characters are escaped. For example lucene-querybuilder for Python, php-lucene-query for PHP or lucene-query-generator for Node.
Paging with start and size
Page through results with start and size: start is the offset of the first result. You can page through the first 10,000 results this way. Beyond that, use search_.
For orders, transactions, payment links, API calls and webhooks, hits counts up to 10,000. For merchants, projects and users, it's the exact number.
Paging with search_after
For orders and transactions, page through any number of results with a cursor. It's faster than start for large exports.
Send the first request
Set search_ to "-1" and choose a sort:
curl https://api.example.com/v1/admin/search/orders/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"query": "*",
"size": 100,
"search_after": "-1",
"sort": "created asc"
}'Each result now has a sort field: the value of the sort field of that result, in a list.
Ask for the next page
Send the same request with the sort value of the last result as search_.
Repeat until the page is empty
Keep the same query, sort and size in every request.
You can't combine search_ with start: use one way of paging or the other. Without a sort, search_ sorts by created, oldest first. See Search orders and Search transactions in the API reference.
Objects
The results of each object have their own fields. Orders and transactions are flat: the order's own fields, and the fields of its transaction with a t_ prefix, such as t_ and t_. Merchants, projects, payment links and users come as {"id": ..., "fields": {...}}. Project results include the fields of their merchant, with an m_ prefix.
The fields are listed per object in the API reference. Search any field by name in the query, such as t_ or m_.
Examples
Search merchants by name. Each result has the id and the merchant's fields.
curl https://api.example.com/v1/admin/search/merchants/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{ "query": "\"Acme Coffee\"" }'See Search merchants in the API reference.
Search projects by their ID or name. Each result also has the merchant's fields, with an m_ prefix.
curl https://api.example.com/v1/admin/search/projects/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{ "query": "c5078bef-f741-4f26-a13f-26e7916bb00c" }'See Search projects in the API reference.
Find the API calls about one merchant, leaving out GET requests and searches:
curl https://api.example.com/v1/admin/search/apicalls/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"query": "b8a1c2d4-1234-4c5d-9e8f-0123456789ab -request_method:GET -request_path:search",
"size": 10,
"sort": "created desc"
}'See Search API calls in the API reference.
Find the last webhook calls to a merchant's URL, with the response the merchant's server gave:
curl https://api.example.com/v1/admin/search/webhooks/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"query": "request_url:*example.com*",
"size": 10,
"sort": "send desc"
}'See Search webhooks in the API reference.
API reference
See Search orders and the other operations under Search in the API reference.