--- id: search title: "Search orders" sidebar_label: Search orders hide_title: true description: "Management API - Orders - Search Orders" --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import Ingress from "../../../src/components/ingress/ingress.react"; import OrderBase from "./models/orderBase.mdx"; import Response from "./models/response.mdx"; The Merchant Hub provides an API over a powerful search engine to let you do fast reliable searches of all your orders and customers. ## Searching To perform a search for orders or attached properties to orders, a GET request is performed against the `/manage/orders` endpoint. ### Simple search The default response is a list of orders sorted by created date descending. There is a limit that is defaulted to 10 orders per page. ```http GET /manage/orders HTTP/1.1 Host: api.uat.walleydev.com // Test environment. Production uses a different hostname. Content-Type: application/json Authorization: Bearer {{accessToken}} ``` ```json { "data": [ { "id": "c75f9525-ac1a-484e-8f9e-acd800cd1e3d", "orderNumber": "MX_210223_132648", "merchantId": "5DFFF2F1", "storeId": 9664, "paymentMethod": "Invoice", "totalAmount": 2168.88, "totalVat": 433.78, "currency": "SEK", "status": "Activated", "countryCode": "SE", "placedAt": "2021-04-29T13:26:48.8534534+02:00", "expiresAt": null, "customerDetails": { "type": "Person", "name": "Mats Edström", "firstName": "Mats", "lastName": "Edström", "customerId": 8271403, "registrationNumber": "9806039955", "countryCode": "SE", "addressLine1": "Finksvängen 38", "city": "Malung", "postalCode": "885 35", "email": "mats.edstrom@sink.walleydev.com", "mobilePhoneNumber": "+46731234567", "homePhoneNumber": "+46731234567" }, "deliveryAddress": { "addressLine1": "Finksvängen 38", "addressLine2": null, "city": "Malung", "coAddress": null, "receiverName": "Mats Edström", "countryCode": "SE", "email": "mats.edstrom@sink.walleydev.com", "mobilePhone": "+46731234567", "phoneNumber": "+46731234567", "postalCode": "885 35" }, "invoiceAddress": { "addressLine1": "Finksvängen 38", "addressLine2": null, "city": "Malung", "coAddress": null, "receiverName": "Mats Edström", "countryCode": "SE", "email": "mats.edstrom@sink.walleydev.com", "mobilePhone": "+46731234567", "phoneNumber": "+46731234567", "postalCode": "885 35" }, "tags": [ "all-all-all", "all-all-orderdetails", "all-9664-all", "all-9664-orderdetails", "5DFFF2F1-all-all", "5DFFF2F1-all-orderdetails", "5DFFF2F1-9664-all", "5DFFF2F1-9664-orderdetails" ] }, { "id": "ec3375c9-8a66-46e3-97cb-acd800cd049e", "orderNumber": "MX_210223_132624", "merchantId": "5DFFF2F1", "storeId": 9664, "paymentMethod": "Invoice", "totalAmount": 31.18, "totalVat": 6.24, "currency": "SEK", "status": "Activated", "countryCode": "SE", "placedAt": "2021-04-29T13:26:27.0930646+02:00", "expiresAt": null, "customerDetails": { "type": "Person", "name": "Petra Ekblom", "firstName": "Petra", "lastName": "Ekblom", "customerId": 8271402, "registrationNumber": "9501059589", "countryCode": "SE", "addressLine1": "Rönnsvängen 6", "city": "Öxnevalla", "postalCode": "348 47", "email": "petra.ekblom@sink.walleydev.com", "mobilePhoneNumber": "+46731234567", "homePhoneNumber": "+46731234567" }, "deliveryAddress": { "addressLine1": "Rönnsvängen 6", "addressLine2": null, "city": "Öxnevalla", "coAddress": null, "receiverName": "Petra Ekblom", "countryCode": "SE", "email": "petra.ekblom@sink.walleydev.com", "mobilePhone": "+46731234567", "phoneNumber": "+46731234567", "postalCode": "348 47" }, "invoiceAddress": { "addressLine1": "Rönnsvängen 6", "addressLine2": null, "city": "Öxnevalla", "coAddress": null, "receiverName": "Petra Ekblom", "countryCode": "SE", "email": "petra.ekblom@sink.walleydev.com", "mobilePhone": "+46731234567", "phoneNumber": "+46731234567", "postalCode": "348 47" }, "tags": [ "all-all-all", "all-all-orderdetails", "all-9664-all", "all-9664-orderdetails", "5DFFF2F1-all-all", "5DFFF2F1-all-orderdetails", "5DFFF2F1-9664-all", "5DFFF2F1-9664-orderdetails" ] } ], "links": { "self": { "method": "GET", "href": "/manage/orders?page=1&perPage=10", "query": "page=1&perPage=10" }, "next": { "method": "GET", "href": "/manage/orders?page=2&perPage=10", "query": "page=2&perPage=10" } }, "metaData": { "totalNumberOfRecords": 32672, "numberOfPages": 3268, "currentPage": 1, "range": { "from": 1, "to": 10 } } } ``` | Http status code | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | | 401 | Unauthorized, token verification needed. See: [Authentication](/docs/manage/getting-started/authentication) for more information | | 403 | No permission for this store | | 404 | Search not found | ### Using search phrases To perform a search with a search phrase you include a `query` parameter in the request querystring. Almost anything on the order can be searched for, including `Order Number`, `Purchase Identifier` or a Customers data like `Reg no`, `name`, `email`, `phone`, `address` The following request performs a search with the phrase `ABC123`: ```text /manage/orders?query=ABC123 ``` ### Using filters Use filters for a search if you want to filter for a specific property or maybe a period of time like all orders placed between two dates. To use filters add one or several `filter` parameters to the request querystring. ```text /manage/orders?query=ABC123&filter=status:["activated"]&filter=storeId:["1158"]&filter=placedAt:["2021-03-01","2021-03-04"] ``` #### Filter examples | Example | Description | | --------------------------------------------- | -------------------------------------------------------------------- | | `filter=status:["Activated", "NotActivated"]` | Return only orders that are in status Activated or NotActivated | | `filter=storeId:["1158", "1433"]` | Return only orders for stores 1158 and 1433 | | `filter=placedAt:["2021-03-01","2021-03-04"]` | Return only orders that are placed between 2021-03-01 and 2021-03-04 | | `filter=placedAt:["","2021-03-04"]` | Return only orders that are placed before 2021-03-04 | ### Pagination Add the `perPage` querystring parameter to control how many orders come back, and `page` to control which page you get. The following request will return page 2 of all pages when there are 30 orders per page: ```text /manage/orders?query=ABC123&page=2&perPage=30 ``` #### Paging metadata The `metaData` object of the response provides information about the paging and total values. ```json { "metaData": { "totalNumberOfRecords": 32672, "numberOfPages": 3268, "currentPage": 1, "range": { "from": 1, "to": 10 } } } ``` | Property | Description | | ------------------------ | -------------------------------------------------------------- | | **totalNumberOfRecords** | The total number of records that matched the current criteria | | **numberOfPages** | The total number of pages available | | **currentPage** | The currently displayed page | | **range** | The from and to positions of search results currently returned | #### Following links ```json { "links": { "self": { "method": "GET", "href": "/manage/orders?page=2&perPage=30", "query": "page=2&perPage=30" }, "next": { "method": "GET", "href": "/manage/orders?page=3&perPage=30", "query": "page=3&perPage=30" }, "prev": { "method": "GET", "href": "/manage/orders?page=1&perPage=30", "query": "page=1&perPage=30" } } } ``` ### Sorting Sorting for a specific property of the response can be accomplished by adding the `sort` querystring property. Valid values are property name followed by `-asc` or `-desc` for ascending or descending sort. ```text /manage/orders?query=ABC123&sort=paymentMethod-desc ``` #### Sortable fields Currently sortable fields are | Field | Description | | ------------------------ | --------------------------------------------------- | | **PlacedAt** | Timestamp when the order was placed | | **ExpiresAt** | Timestamp when the order expires if not activated | | **OrderNumber** | The order number | | **StoreId** | The merchant store id | | **customerDetails.name** | The name of the customer | | **Status** | The status of the order | | **PaymentMethod** | The payment method of the order | | **TotalAmount** | The total amount of the order, excl. financial fees | ## Data Model ### Request #### Request headers | Header | Required | Explanation | | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | Yes | See [Authentication](/docs/manage/getting-started/authentication) for how to generate the Bearer token value | ### Response `response.data` object is an array of the following structure: #### links `response.links` See [following links section](#following-links) #### metaData `response.metaData` See [paging metadata](#paging-metadata)