Skip to main content

Searching for Orders

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 /orders endpoint.

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.

GET /orders HTTP/1.1
Host: api.uat.walleydev.com // (Please  note! Different hostname in production)
Content-Type: application/json
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Http status codeDescription
200OK
401Unauthorized, token verification needed. See: Authentication for more information
403Permissions needed e.g. trying to handle content for a store you don't have permission to
404Search 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:

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

/manage/orders?query=ABC123&filter=status:["activated"]&filter=storeId:["1158"]&filter=placedAt:["2021-03-01","2021-03-04"]

Filter examples​

ExampleDescription
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​

You can control how many orders that are returned by setting the perpage request property and control which page to return by setting the page property.

The following request will return page 2 of all pages when there are 30 orders per page:

/manage/orders?query=ABC123&page=2&perpage=30

Paging metadata​

The metaData object of the response provides information about the paging and total values.

"metaData": {
    "totalNumberOfRecords": 32672,
    "numberOfPages": 3268,
    "currentPage": 1,
    "range": {
      "from": 1,
      "to": 10
    }
PropertyDescription
totalNumberOfRecordsThe total number of records that matched the current criteria
numberOfPagesThe total number of pages available
currentPageThe currently displayed page
rangeThe from and to positions of search results currently returned
{
  "links": {
    "self": {
      "method": "GET",
      "href": "/orders?page=2&perPage=30",
      "query": "page=2&perPage=30"
    },
    "next": {
      "method": "GET",
      "href": "/orders?page=3&perPage=30",
      "query": "page=3&perPage=30"
    },
    "prev": {
      "method": "GET",
      "href": "/orders?page=1&perPage=30",
      "query": "page=1&perPage=30"
    }
  }
}

Sorting​

Sorting for a specific property of the response can be acomplished by adding the sort querystring property. Valid values are property name followed by -asc or -desc for ascending or descending sort.

/manage/orders?query=ABC123&sort=paymentMethod-desc

Sortable fields​

Currently sortable fields are

FieldDescription
PlacedAtTimestamp when the order was placed
ExpiresAtTimestamp when the order expires if not activated
OrderNumberThe order number
StoreIdThe merchant store id
customerDetails.nameThe name of the customer
StatusThe status of the order
PaymentMethodThe payment method of the order
TotalAmountThe total amount of the order, excl. financial fees

Data Model​

Request​

Request headers

HeaderRequiredExplanation
AuthorizationYesInstructions on how to generate the Bearer token value can be found here

Response​

This is the main structure of the response object:

{
  "data": [],
  "links": {},
  "metaData": {}
}

response.data object is an array of the following structure:

Example​
{
  "id": "853f3f82-ab12-47c3-9d97-af17009852cd",
  "reference": "MX_220921_111434",
  "paymentMethod": "Invoice",
  "totalAmount": 2362.36,
  "currency": "SEK",
  "status": "Activated",
  "salesSegment": "B2C",
  "countryCode": "SE",
  "productCode": "DI_001",
  "placedAt": "2022-09-21T11:14:35.7900411+02:00",
  "expiresAt": null,
  "customer": {
    /*...*/
  },
  "deliveryAddress": {
    /*...*/
  },
  "invoiceAddress": {
    /*...*/
  },
  "items": [
    /*...*/
  ],
  "invoices": [
    /*...*/
  ]
}
PropertyExplanation
idThe id of the order
referenceThe order number/reference set by merchant at point of purchase
paymentMethodThe method used by the end customer to perform the Purchase. Invoice, Account, Installment, Card, BankTransfer, Swish, InterestFreeAccount
totalAmountThe total amount of the order excluding financial fees
currencyThe currency of the order
statusThe status of the entire order. NotActivated, Activated, PartActivated, Returned, Expired, OnHold, Closed
salesSegmentThe type of endcustomer that made the order, B2C, B2B
countryCodeThe country code of the market where the order was placed
productCodeThe product code used for the payment method
placedAtTimestamp in UTC of when the order was placed
expiresAtTimestamp in UTC of when the order expires if not activated
customerCustomer specific details. See Customer
deliveryAddressDelivery address. See Address
invoiceAddressInvoicing address. See Address
itemsAll items of the order See Items
invoicesList of invoices the end customer has been notified. See Invoice

response.links See following links section

metaData​

response.metaData See paging metadata