Skip to content

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:

PathSearches
/v1/admin/search/{object}/All merchants of your platform. For admins: an admin user's token. Ask your Ginger contact whether your admin API key works here too.
/v1/search/{object}/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.

ObjectPathResults in
Orders.../search/orders/orders
Transactions.../search/transactions/transactions
Merchants.../search/merchants/merchants. Admins only: /v1/search/merchants/ returns 403 Forbidden.
Projects.../search/projects/projects, with the fields of their merchant
Users.../search/users/users
Payment links.../search/paymentlinks/payment_links
API calls.../search/apicalls/apicalls, the log of requests to the API
Webhooks.../search/webhooks/webhook_calls, the log of webhook calls to merchants
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_after. 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:

QueryFinds
*Everything
fdd81581-28b0-42fc-8be7-9228762d9368Objects with this value in any field, such as an ID
status:completedObjects with this value in the status field
status:completed currency:EURBoth: 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_method:GETEverything except GET requests, in the API call log
request_url:*example*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_after.

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_after 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_after.

Repeat until the page is empty

Keep the same query, sort and size in every request.

You can't combine search_after with start: use one way of paging or the other. Without a sort, search_after 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_status and t_payment_method. 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_payment_method:credit-card or m_status:active.

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.

API reference

See Search orders and the other operations under Search in the API reference.