---
id: search
title: "Settlement search"
sidebar_label: Settlement search
hide_title: true
description: "Reports API - Settlements - Search"
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Ingress from "../../../src/components/ingress/ingress.react";

<Ingress title="Settlement search">
  Find settlement reports for all your stores. Walley creates one settlement
  report each time a store is settled according to your agreement.
</Ingress>

## Example

<Tabs defaultValue="req" values={[
{ label: 'Request', value: 'req', },
{ label: 'Response', value: 'res', }
]}>

<TabItem value="req">

```http
GET /reports/settlements?page=1&perPage=1 HTTP/1.1
Host: api.uat.walleydev.com // Test environment. Production uses a different hostname.
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
```

</TabItem>

<TabItem value="res">

```json
{
  "data": [
    {
      "id": "1",
      "startDate": "2022-12-30T00:00:00",
      "endDate": "2022-12-30T00:00:00",
      "storeId": 1,
      "ingoingBalance": 0.0,
      "totalAmount": 100000.0,
      "currency": "SEK",
      "netSales": 100000.0,
      "paidOutAt": "2023-01-02T11:00:10.000000+01:00",
      "generatedAt": "2023-01-02T11:00:10.000000+01:00",
      "captured": 103000.0,
      "refunded": -3000.0,
      "reference": "2134",
      "compensations": 0.0,
      "adjustments": 0.0,
      "links": {
        "pdf": {
          "method": "GET",
          "href": "/reports/settlements/1/file/pdf",
          "query": ""
        },
        "transactions": {
          "method": "GET",
          "href": "/reports/settlements/1/transactions",
          "query": ""
        }
      }
    }
  ],
  "links": {
    "self": {
      "method": "GET",
      "href": "/settlements?page=1&perPage=1",
      "query": "page=1&perPage=1"
    },
    "next": {
      "method": "GET",
      "href": "/settlements?page=2&perPage=1",
      "query": "page=2&perPage=1"
    }
  },
  "metaData": {
    "totalNumberOfRecords": 100,
    "numberOfPages": 100,
    "currentPage": 1,
    "range": {
      "from": 1,
      "to": 1
    }
  }
}
```

</TabItem>

</Tabs>

| Http status code | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| 200              | Successful request                                                                                                |
| 401              | Token missing, expired, or invalid. See [Authentication](/docs/reports/authentication)                             |
| 409              | Request with same idempotency key already in progress                                                             |
| 422              | Query with incorrect format                                                                                       |

## Data Model

### Request

#### Request headers

| Header            | Required | Explanation                                                                                              |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| **Authorization** | Yes      | See [Authentication](/docs/reports/authentication) for how to generate the Bearer token value |

#### Request querystrings

| Parameter   | Required | Explanation                                                                                                                                      |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **page**    | No       | Page of items that should be returned in request. Default is 1                                                                                   |
| **perPage** | No       | Number of items to be returned in each request. Largest allowed value is 1000, default is 10                                                     |
| **query**   | No       | Used for free text search or specific property value search. See [Request examples](#request-examples)                                          |

#### Request examples

The **query** parameter can be used in the request to filter settlement reports on the [properties](/docs/reports/settlements-api/search#properties).

:::note `%20` is a URL-encoded space
The example URLs below encode every space in the query as `%20`.
:::

##### By date and periods

Reports that have **startDate** after the date 2022-12-17. This is equal to the search `startDate:>2022-12-17`.

```text
/reports/settlements?query=startDate:>2022-12-17&page=1&perPage=30
```

Reports that have **startDate** before the date 2022-12-17. This is equal to the search `startDate:<2022-12-17`.

```text
/reports/settlements?query=startDate:<2022-12-17&page=1&perPage=30
```

Reports with the **startDate** 2022-12-30 and **endDate** 2022-12-30. This is equal to the search `startDate:2022-12-30 AND endDate:2022-12-30`.

```text
/reports/settlements?query=startDate:2022-12-30%20AND%20endDate:2022-12-30&page=1&perPage=30
```

Reports between **startDate** 2022-12-01 and **endDate** 2022-12-08. This is equal to the search `startDate:>=2022-12-01 AND endDate:<=2022-12-08`.

```text
/reports/settlements?query=startDate:>=2022-12-01%20AND%20endDate:<=2022-12-08&page=1&perPage=30
```

##### By currency

Reports with the **currency** SEK.

```text
/reports/settlements?query=currency:SEK&page=1&perPage=30
```

##### By store

Reports from the **storeId** 4567.

```text
/reports/settlements?query=storeId:4567&page=1&perPage=30
```

##### By settlement reference

Reports with the **reference** 2134.

```text
/reports/settlements?query=reference:2134&page=1&perPage=30
```

##### Combined properties

Reports between the time period **startDate** 2022-12-01 and **endDate** 2022-12-08 with currency SEK.
Equal to `startDate:>=2022-12-01 AND endDate:<=2022-12-08 AND currency:SEK`.

```text
/reports/settlements?query=startDate:>=2022-12-01%20AND%20endDate:<=2022-12-08%20AND%20currency:SEK&page=1&perPage=30
```

Reports from the **storeId** 1158 with currency SEK.
Equal to `storeId:1158 AND currency:SEK`.

```text
/reports/settlements?query=storeId:1158%20AND%20currency:SEK&page=1&perPage=30
```

### Response

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

```json
{
  "id": "1",
  "startDate": "2022-12-30T00:00:00",
  "endDate": "2022-12-30T00:00:00",
  "storeId": 1,
  "ingoingBalance": 0.0,
  "totalAmount": 100000.0,
  "currency": "SEK",
  "netSales": 100000.0,
  "paidOutAt": "2023-01-02T11:00:10.000000+01:00",
  "generatedAt": "2023-01-02T11:00:10.000000+01:00",
  "captured": 103000.0,
  "refunded": -3000.0,
  "reference": "2134",
  "compensations": 0.0,
  "adjustments": 0.0,
  "links": {
    "pdf": {
      "method": "GET",
      "href": "/reports/settlements/1/file/pdf",
      "query": ""
    },
    "transactions": {
      "method": "GET",
      "href": "/reports/settlements/1/transactions",
      "query": ""
    }
  }
}
```

### Properties

| Property               | Explanation                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **id**                 | The id of the settlement                                                                                                     |
| **startDate**          | The start date of captures and refunds that are included in the settlements                                                     |
| **endDate**            | The end date of captures and refunds that are included in the settlements                                                       |
| **storeId**            | The id of the store that has been settled                                                                                    |
| **ingoingBalance**     | If the previous settlement had a negative balance, it is carried over to the following settlement                            |
| **totalAmount**        | The amount that will be paid out for the period                                                                             |
| **currency**           | The currency of the settled purchases                                                                                        |
| **netSales**           | The net sales during the settled period                                                                                      |
| **paidOutAt**          | The date of the payout                                                                                                       |
| **generatedAt**        | The date and time the settlement was generated                                                                               |
| **captured**           | The captured amount during the settlement period                                                                             |
| **refunded**           | The returned amount during the settlement period                                                                             |
| **reference**          | The settlement reference (only shown for merchants with settlement reference option activated)                               |
| **compensations**      | The sum of all Walley fees for the settlement period                                                                         |
| **adjustments**        | Settlement adjustments. See [Manual adjustment types](/docs/reports/settlements-api/settlement-types#manual-adjustment-types) |
| **links.transactions** | The URL for retrieving all the settled transactions                                                                          |
| **links.pdf**          | The URL for retrieving the settlement's PDF file. Depending on setup, it might not be available.                             |