> 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/search-for-orders-in-the-external-order-system.md).

# Search for orders in the external order system

Search for orders in the tenant's external order system.

Requires the EXTERNAL\_ORDER\_SEARCH extension to be active on the tenant, pointing at the extension that does the searching.

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Order","description":"Order"}],"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"}},"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"}}},"responses":{"ExternalOrderListResponse":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExternalOrderResponseSchema"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["items","paging"],"type":"object"}}},"description":"Example response"}},"schemas":{"ExternalOrderResponseSchema":{"type":"object","title":"ExternalOrderResponseSchema","description":"An order found in the tenant's external order system. It carries the fields a till\nneeds to recognise the order and credit lines on it, and they use the same names as\non OrderResponseSchema.\n\nThe order has not been imported into Flow, so anything Flow owns is filled in only\nwhen the external system happens to hold it: storeUid and storeName are left out\nwhen the order carries no store Flow knows, and customerUid is empty when the\nexternal system does not hold a Flow customer.","required":["orderUid","orderNumber","createdAt","customerAddress","customerUid","note","orderTotals","tenantUserDisplayName","voucherNumber","items"],"properties":{"orderUid":{"description":"The order's id in the external system. It is the same value the order gets as its orderUid if it is imported into Flow.","$ref":"#/components/schemas/UID"},"orderNumber":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"customerAddress":{"$ref":"#/components/schemas/OrderAddressResponseSchema"},"customerUid":{"description":"The Flow customer the external system holds on the order. Empty when it holds an id Flow does not know.","$ref":"#/components/schemas/OptionalUID"},"note":{"description":"Note visible on the receipt.","type":"string"},"orderTotals":{"$ref":"#/components/schemas/ExternalOrderTotalsSchema"},"storeUid":{"description":"The store the order was placed in. Left out when the external system holds no store Flow knows.","$ref":"#/components/schemas/UID"},"storeName":{"description":"The name of the store the order was placed in. Left out together with storeUid.","type":"string"},"tenantUserDisplayName":{"description":"Who registered the order in the external system. Empty when it does not say.","type":"string"},"voucherNumber":{"description":"A reference to a fully settled order. Empty when the order has none.","type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ExternalOrderItemSchema"}}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"OrderAddressResponseSchema":{"title":"OrderAddressResponseSchema","type":"object","required":["address","city","companyName","countryCode","email","firstname","lastname","mobile","postalCode","displayName"],"properties":{"address":{"type":"string"},"city":{"type":"string"},"companyName":{"type":"string"},"countryCode":{"type":"string"},"email":{"$ref":"#/components/schemas/EmailTYPE"},"firstname":{"type":"string"},"lastname":{"type":"string"},"mobile":{"type":"string"},"postalCode":{"type":"string"},"vatNumber":{"$ref":"#/components/schemas/VatNumberTYPE"},"displayName":{"type":"string"}},"description":""},"EmailTYPE":{"title":"Email","type":"string"},"VatNumberTYPE":{"description":"VAT identification number for value added tax reporting purposes.","title":"VatNumber","type":"string"},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"ExternalOrderTotalsSchema":{"type":"object","title":"ExternalOrderTotalsSchema","description":"What the order comes to in the external order system. Only the grand total, the one figure a till needs to show the order.","required":["grandTotal"],"properties":{"grandTotal":{"type":"integer"}}},"ExternalOrderItemSchema":{"type":"object","title":"ExternalOrderItemSchema","description":"A product line on an order in the external order system. The fields carry the same\nnames and the same scale as on OrderItemResponseSchema: quantities in hundredths,\namounts in minor units.","required":["orderItemUid","allowedActions","createdAt","sku","name","note","productUid","itemPrice","itemDiscountAmount","totalPrice","totalDiscountAmount","quantityOrdered","quantityCredited","quantityDelivered","quantityReserved","serialnumber","sortOrder","tenantUserDisplayName"],"properties":{"orderItemUid":{"description":"The line's id in the external system.","$ref":"#/components/schemas/UID"},"allowedActions":{"description":"What the till is allowed to do with the line. An external order line can be credited, so this is CREDIT.","type":"array","items":{"$ref":"#/components/schemas/AllowedActionENUM"}},"createdAt":{"description":"When the order was created. The external system keeps no separate date per line.","format":"date-time","type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"note":{"type":"string"},"productUid":{"description":"The Flow product the sku matches. Empty when the tenant has no product with that sku.","$ref":"#/components/schemas/OptionalUID"},"coverImage":{"description":"The cover image of the Flow product the sku matches. Left out when there is no matching product, or it has no cover image.","$ref":"#/components/schemas/CoverImageSchema"},"itemPrice":{"description":"Price for a single product.","type":"integer"},"itemDiscountAmount":{"description":"Discount amount for a single product.","type":"integer"},"totalPrice":{"description":"Total price for all products on this line.","type":"integer"},"totalDiscountAmount":{"description":"Discount amount for all products on this line.","type":"integer"},"quantityOrdered":{"description":"In hundredths (100 = 1 unit).","type":"integer"},"quantityCredited":{"description":"In hundredths (100 = 1 unit).","type":"integer"},"quantityDelivered":{"description":"In hundredths (100 = 1 unit).","type":"integer"},"quantityReserved":{"description":"In hundredths (100 = 1 unit).","type":"integer"},"serialnumber":{"type":"string"},"sortOrder":{"description":"The line number the order has in the external system.","type":"integer"},"tenantUserDisplayName":{"description":"Who registered the line in the external system. Empty when it does not say.","type":"string"}}},"AllowedActionENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| QUANTITY_SOLD | Can change quantity on order item|\n| PRICE_SALE | Can change price on order item|\n| DISCOUNT | Can set discount on order item|\n| SERIALNUMBER | Can set serial number on order item|\n| SERIALNUMBER_REQUIRED | MUST set serial number on order item|\n| CREDIT | Order item can be credited|\n| ADDON | Product on order item has addons|\n| CUSTOMER_REQUIRED | Order item requires customer on settlement|\n| CUSTOMER_MOBILE_REQUIRED | Order item requires customer mobile number on settlement|\n| CUSTOMER_EMAIL_REQUIRED  - Order item requires customer email on settlement|\n| DELIVERY_POSTAL_ADDRESS_REQUIRED | Order item requires delivery address on settlement|\n| INSURANCE | Order item can be insured|\n| DELETE | Order item can be deleted|   \n| DELIVER | Order item can be delivered|\n| PURCHASE | Order item can be marked as purchase from supplier |\n| COST_PRICE | Set cost price on the orderItem |\n| PRODUCT_NAME | Set name of the product on the orderItem |\n| PAYABLE | order item is payable |\n| NEGATIVE_PRICE| Can have negative price |","enum":["QUANTITY_SOLD","PRICE_SALE","DISCOUNT","SERIALNUMBER","SERIALNUMBER_REQUIRED","CREDIT","ADDON","CUSTOMER_REQUIRED","INSURANCE","CUSTOMER_MOBILE_REQUIRED","CUSTOMER_EMAIL_REQUIRED","DELIVERY_POSTAL_ADDRESS_REQUIRED","DELETE","DELIVER","PURCHASE","COST_PRICE","PRODUCT_NAME","PAYABLE","NEGATIVE_PRICE"],"title":"AllowedActionENUM","type":"string"},"CoverImageSchema":{"title":"CoverImageSchema","type":"object","properties":{"productMediaUid":{"$ref":"#/components/schemas/OptionalUID"},"mainUrl":{"type":"string"},"thumbnailUrl":{"type":"string"}},"required":["productMediaUid","mainUrl","thumbnailUrl"]},"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"},"ExternalOrderSearchSchema":{"type":"object","title":"ExternalOrderSearchSchema","description":"Search criteria for orders in the external order system.","properties":{"query":{"description":"Free text search. Matches order number, customer and product lines.","type":"string"},"storeUids":{"description":"Narrow the search to these stores. The caller must have access to every store\nlisted, and they must all belong to the same organization.\n\nLeave it out to search every order the tenant has in the external system. Note\nthat orders which did not originate in Flow may not carry a store at all, so a\nstore filter hides them.","type":"array","items":{"$ref":"#/components/schemas/UID"}},"customerUids":{"description":"Narrow the search to these customers. These are Flow customer uids — the\nsearch resolves each one to the id the external system holds on the order,\nwhich is the customer's external id when it has one and the Flow uid\notherwise, and asks for both.\n\nLeave it out to search orders for every customer. A uid the tenant does not\nhave is an error, not an empty result.","type":"array","items":{"$ref":"#/components/schemas/UID"}}}}},"requestBodies":{"ExternalOrderSearchRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalOrderSearchSchema"}}}}}},"paths":{"/tenants/{tenantUid}/orders/search/external":{"post":{"description":"Search for orders in the tenant's external order system.\n\nRequires the EXTERNAL_ORDER_SEARCH extension to be active on the tenant, pointing at the extension that does the searching.","operationId":"post-tenants-orders-search-external","parameters":[{"$ref":"#/components/parameters/pageNumberQuery"},{"$ref":"#/components/parameters/pageSizeQuery"}],"responses":{"200":{"$ref":"#/components/responses/ExternalOrderListResponse"}},"summary":"Search for orders in the external order system","tags":["Order"],"requestBody":{"$ref":"#/components/requestBodies/ExternalOrderSearchRequest"}}}}}
```


---

# 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/search-for-orders-in-the-external-order-system.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.