# Statistics customer analytics

> Base URL: `https://pos.pages.fm/api/v1`. Authenticate with the `api_key` query parameter.

## Customer overview report

`GET /shops/{SHOP_ID}/customer_analytics/report`

Get all figures of the Customer overview report (Statistics -> Customer screen) in a single call:
new/old customer counts and spending, gender, age groups, customer levels,
distribution by successful order count, purchase cycle and the paginated customer list.

To paginate / sort / search the customer list only (without recomputing the summary blocks),
call the same endpoint with `section=customer_orders` — the response then contains only `customer_orders`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `startDate` | query | integer |  | Start of the reporting period (unix timestamp, seconds). Customers created from this time are counted as new customers. |
| `endDate` | query | integer |  | End of the reporting period (unix timestamp, seconds) |
| `page` | query | integer |  | Page number of the customer list (default 1) |
| `pageSize` | query | integer |  | Number of customers per page (default 10) |
| `data_sort` | query | string |  | Sort the customer list. JSON-encoded object: - `sort_by`: `order_count` \| `order_success` \| `order_return` \| `order_success_amount` (default) - `asc_desc`: `asc` \| `desc` (default) |
| `search` | query | string |  | Search the customer list by customer name or phone number |
| `section` | query | string |  | Set to `customer_orders` to return only the paginated customer list Values: `customer_orders`. |
| `sale_form` | query | string |  | Filter by sale form (retail / wholesale customers, based on shop wholesale tag settings) Values: `all`, `retail`, `wholesale`. |
| `warehouse_id[]` | query | string[] |  | Filter orders by warehouse |
| `order_sources[]` | query | string[] |  | Filter by order source. Each item is a JSON-encoded object `{"order_sources": "<source>", "account": "<account_id>"}`. Source values are the same as on web (see the `/shops/{SHOP_ID}/order_source` endpoint). |
| `is_filter_exclude_source` | query | string |  | Exclude (instead of include) the sources in `order_sources[]` Values: `true`, `false`. |
| `order_tag[]` | query | string[] |  | Filter orders by order tag IDs. Special value `no_tag` filters orders without tags. |
| `is_filter_tag_by_or` | query | string |  | `true` (default): order matches ANY tag in `order_tag[]`; `false`: order must contain ALL tags Values: `true`, `false`. |
| `is_filter_exclude` | query | string |  | Exclude (instead of include) the tags in `order_tag[]` Values: `true`, `false`. |
| `selectedLevel[]` | query | string[] |  | Filter by customer level IDs (see the `/shops/{SHOP_ID}/customer_levels` endpoint) |
| `gender[]` | query | string[] |  | Filter by customer gender (`none` = no gender information) |
| `typeCustomer[]` | query | string[] |  | Filter by customer type: `online` (has a linked social account) / `offline` |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": {
    "customer": {
      "new_customer": 2,
      "old_customer": 6
    },
    "customer_purchased": {
      "new_customer": "1006000",
      "old_customer": "5870098"
    },
    "customer_gender": {
      "male": 0,
      "female": 0,
      "unknown": 8
    },
    "customer_age": {
      "under_18": 0,
      "revenue_under_18": null,
      "from_18_to_24": 0,
      "revenue_from_18_to_24": null,
      "from_25_to_34": 0,
      "revenue_from_25_to_34": null,
      "from_35_to_44": 0,
      "revenue_from_35_to_44": null,
      "from_45_to_54": 0,
      "revenue_from_45_to_54": null,
      "over_55": 0,
      "revenue_over_55": null,
      "havent_birthday": 8,
      "revenue_total": 6824089
    },
    "customer_level": [
      {
        "id": "2d058084-4219-4ef3-bf4c-e7b77889224c",
        "count": 2,
        "total_amount": "4070000"
      },
      {
        "id": "6c7f0d31-4f5a-43b1-a0d6-b30081e48f5a",
        "count": 1,
        "total_amount": "1050000"
      },
      {
        "id": null,
        "count": 5,
        "total_amount": "1756098"
      }
    ],
    "customer_order_count": [
      {
        "order_success_quantity": 0,
        "customer_count": 8,
        "amount": "0"
      }
    ],
    "new_customer": {
      "old_customer": 6,
      "analytic_new_customer": {
        "count": 2,
        "count_1": 2,
        "count_2": 0,
        "count_tags": 0
      }
    },
    "customer_analytic": [
      {
        "range": 0,
        "from_1_to_30": 0,
        "from_31_to_60": 7,
        "from_61_to_90": 0,
        "under_90": 121,
        "total": 128
      },
      {
        "range": 1,
        "from_1_to_30": 0,
        "from_31_to_60": 2,
        "from_61_to_90": 0,
        "under_90": 7,
        "total": 9
      },
      {
        "range": 31,
        "from_1_to_30": 0,
        "from_31_to_60": 2,
        "from_61_to_90": 0,
        "under_90": 3,
        "total": 5
      },
      {
        "range": 61,
        "from_1_to_30": 0,
        "from_31_to_60": 0,
        "from_61_to_90": 0,
        "under_90": 1,
        "total": 1
      },
      {
        "range": 91,
        "from_1_to_30": 0,
        "from_31_to_60": 0,
        "from_61_to_90": 0,
        "under_90": 3,
        "total": 3
      }
    ],
    "customer_orders": {
      "success": true,
      "page_number": 1,
      "page_size": 30,
      "total_entries": 8,
      "total_pages": null,
      "data": [
        {
          "id": "330fdf15-7301-4d9c-86e6-f6ea21ed37bf",
          "name": "khách colombia",
          "currency": null,
          "phone_number": [
            "0982342873"
          ],
          "customer": {
            "id": "af55aee2-3846-43d7-8f46-13d768462731",
            "name": "khách colombia",
            "global_id": null,
            "fb_id": null,
            "psid": null
          },
          "order_count": 1,
          "order_return_count": 0,
          "order_success_amount": 0,
          "order_success_count": 0
        },
        {
          "id": "941e822e-fc98-4852-bdea-3a8f806cf362",
          "name": "Hoang Anhbcde",
          "currency": "VND",
          "phone_number": [
            "0999999999"
          ],
          "customer": {
            "id": "db647f48-b20d-4fcf-95b4-eb277a2087b9",
            "name": "Hoang Anh",
            "global_id": null,
            "fb_id": null,
            "psid": null
          },
          "order_count": 7,
          "order_return_count": 0,
          "order_success_amount": 0,
          "order_success_count": 0
        }
      ]
    }
  }
}
```