> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/order-settlement/search-in-payments.md).

# Search in payments

Retrieves a filtered list of invoice payments across the organization. One item per registered payment, not per invoice: an invoice paid in two instalments returns two items.

`createdAt` is when the payment was registered in Flow, `paidAt` is the value date supplied by the payer or bank file. Both ranges are applied as-is, so send local start-of-day and end-of-day.

Results are sorted by `createdAt` descending when no sorting parameter is specified. `sortBy` accepts payment fields only: `createdAt`, `paidAt`, `amount`, `createdBy` and `externalReference`. Customer name, invoice number and store name cannot be sorted server-side, and any other value is rejected.

Pending payment attempts (amount 0 with no `paidAt`) are never returned.

Required permissions: PAYMENT,SALES\_ORDER

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"OrderSettlement","description":"OrderSettlement"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"PaymentSearchListResponse":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","required":["items","paging"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSearchResponseSchema"}},"paging":{"$ref":"#/components/schemas/Paging"}}}}}}},"schemas":{"PaymentSearchResponseSchema":{"title":"PaymentSearchResponseSchema","type":"object","required":["paymentUid","amount","externalReference","createdAt","createdBy","orderUid","settlementUid","invoiceNumber","settlementAmount","settlementPaidAmount","remainingAmount","storeUid","storeName","storeExternalId","customerUid","customerName"],"properties":{"paymentUid":{"$ref":"#/components/schemas/UID"},"amount":{"type":"integer","description":"The amount registered by this payment."},"paidAt":{"type":"string","format":"date-time","description":"Value date supplied by the payer or bank file. Absent when none was given."},"externalReference":{"type":"string"},"createdAt":{"type":"string","format":"date-time","description":"When the payment was registered in Flow."},"createdBy":{"type":"string","description":"Display name of the user who registered the payment."},"orderUid":{"$ref":"#/components/schemas/UID"},"settlementUid":{"$ref":"#/components/schemas/UID"},"invoiceNumber":{"type":"string"},"settlementAmount":{"type":"integer","description":"The full invoice amount."},"settlementPaidAmount":{"type":"integer","description":"Sum of all payments registered on the invoice, as of now."},"remainingAmount":{"type":"integer","description":"settlementAmount minus settlementPaidAmount, as of now — not as of this\npayment. Credit notes are not deducted, so a credited invoice reads high."},"storeUid":{"$ref":"#/components/schemas/UID"},"storeName":{"type":"string"},"storeExternalId":{"type":"string","description":"The store's external id, the closest equivalent to a department number. Empty when the store has none."},"customerUid":{"$ref":"#/components/schemas/OptionalUID"},"customerName":{"type":"string","description":"Customer name as it was on the invoice."}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"Paging":{"description":"totalCount The total number of items in the result set.\n\npageSize The number of items per page.\n\npageNumber The current page in the result set.","properties":{"pageNumber":{"type":"integer"},"pageSize":{"type":"integer"},"totalCount":{"type":"integer"}},"required":["totalCount","pageSize","pageNumber"],"title":"Paging","type":"object"},"PaymentSearchRequestSchema":{"title":"PaymentSearchRequestSchema","type":"object","description":"Filters for the payment search. Every field is optional, and an empty object\nreturns every payment in the organization.","properties":{"createdAt":{"$ref":"#/components/schemas/DateTimeRangeSchema"},"paidAt":{"$ref":"#/components/schemas/DateTimeRangeSchema"},"createdBy":{"type":"array","description":"Display names of the users who registered the payments, matched\nexactly. This is a snapshot taken when the payment was registered,\nso it does not follow a later rename of the user.","items":{"type":"string"}},"storeUids":{"type":"array","description":"The stores that issued the invoices, not the store where a payment was taken.","items":{"$ref":"#/components/schemas/UID"}}}},"DateTimeRangeSchema":{"title":"DateTimeRangeSchema","type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"SortDirectionENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| ASC | Sort in ascending order|\n| DESC | Sort in descending order|\n","enum":["ASC","DESC"],"title":"SortDirectionENUM","type":"string"}},"requestBodies":{"PaymentSearchRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSearchRequestSchema"}}}}},"parameters":{"pageNumberQuery":{"description":"Reference to a specific page in a result set.","in":"query","name":"pageNumber","required":false,"schema":{"type":"integer"}},"pageSizeQuery":{"description":"The number of items per page in a result set.","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}},"sortByQuery":{"description":"Defines which field the resource list is sorted by.","in":"query","name":"sortBy","required":false,"schema":{"type":"string"}},"sortDirectionQuery":{"description":"Reference to a sort direction","explode":false,"in":"query","name":"sortDirection","schema":{"$ref":"#/components/schemas/SortDirectionENUM"},"style":"form"}}},"paths":{"/tenants/{tenantUid}/organizations/{organizationUid}/payments/search":{"post":{"summary":"Search in payments","tags":["OrderSettlement"],"responses":{"200":{"$ref":"#/components/responses/PaymentSearchListResponse"}},"operationId":"post-payments-search","description":"Retrieves a filtered list of invoice payments across the organization.\nOne item per registered payment, not per invoice: an invoice paid in two\ninstalments returns two items.\n\n`createdAt` is when the payment was registered in Flow, `paidAt` is the\nvalue date supplied by the payer or bank file. Both ranges are applied\nas-is, so send local start-of-day and end-of-day.\n\nResults are sorted by `createdAt` descending when no sorting parameter is\nspecified. `sortBy` accepts payment fields only: `createdAt`, `paidAt`,\n`amount`, `createdBy` and `externalReference`. Customer name, invoice\nnumber and store name cannot be sorted server-side, and any other value\nis rejected.\n\nPending payment attempts (amount 0 with no `paidAt`) are never returned.\n\nRequired permissions: PAYMENT,SALES_ORDER","requestBody":{"$ref":"#/components/requestBodies/PaymentSearchRequest"},"parameters":[{"$ref":"#/components/parameters/pageNumberQuery"},{"$ref":"#/components/parameters/pageSizeQuery"},{"$ref":"#/components/parameters/sortByQuery"},{"$ref":"#/components/parameters/sortDirectionQuery"}]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/api-documentation/order-settlement/search-in-payments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.