# Customer

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

## Customer list

`GET /shops/{SHOP_ID}/customers`

Get list of customers

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `page_size` | query | integer |  | Page size |
| `page_number` | query | integer |  | Page number |
| `search` | query | string |  | Search keyword |
| `start_time_inserted_at` | query | integer |  | Start time inserted |
| `end_time_inserted_at` | query | integer |  | End time inserted |
| `start_time_updated_at` | query | integer |  | Start time updated |
| `end_time_updated_at` | query | integer |  | End time updated |
| `customer_ids` | query | string |  | Customer IDs (comma-separated) |
| `selectedLevel[]` | query | string[] |  | Customer level IDs |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "id": "b0110315-b102-436b-8b3b-ed8d16740327",
      "name": "Trần Văn Hoàng",
      "gender": "male",
      "emails": [
        "thudo@gmail.com"
      ],
      "phone_numbers": [
        "0999999999"
      ],
      "date_of_birth": "1999-09-01",
      "reward_point": 10,
      "is_discount_by_level": true,
      "tags": [],
      "is_block": false,
      "assigned_user_id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
      "level_id": null,
      "notes": [],
      "shop_customer_address": [
        {
          "id": "0fefd213-7d0c-4d5b-bdbf-35694da80857",
          "country_code": null,
          "province_id": "101",
          "district_id": "10101",
          "commune_id": null,
          "address": "lê văn lương",
          "full_address": "lê văn lương, Quận Ba Đình, Hà Nội",
          "full_name": "test",
          "phone_number": "0999999999"
        }
      ],
      "order_count": 108,
      "purchased_amount": 0,
      "succeed_order_count": 8,
      "last_order_at": "2020-04-01T10:18:41Z",
      "conversation_link": "https://pancake.vn/2284322048329488?customer_id=fc0dda4f-8d2a-4e70-a34a-7a6a434c6475",
      "referral_code": "1nw4geGA",
      "fb_id": null,
      "customer_id": "96a8e283-3fba-492e-a35a-970f72a30a02",
      "pages_customers": [
        {
          "id": 256469571170000,
          "name": "Clonners",
          "platform": "facebook"
        }
      ]
    }
  ]
}
```

## Create customer

`POST /shops/{SHOP_ID}/customers`

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |

### Request body

Request body containing customer information to create

- `name` (string, required): Customer name
- `phoneNumber` (string, required): Phone number
- `createType` (string): Create type
- `dateOfBirth` (string (date)): Date of birth
- `last_order_at` (integer): Last order timestamp
- `shop_customer_address` (object[]): Customer addresses
  - `full_address` (string): Full address
  - `full_name` (string): Full name
  - `phone_number` (string): Phone number

```json
{
  "name": "Hoang",
  "phoneNumber": "0909090909",
  "createType": "force",
  "dateOfBirth": "1995-02-01",
  "last_order_at": 1715878800,
  "shop_customer_address": [
    {
      "full_address": "190, phường dịch vọng, cầu giấy, hà nội",
      "full_name": "hoang",
      "phone_number": "0972868874"
    },
    {
      "full_address": "190, Mỹ đình 2, Nam từ liêm, hà nội",
      "full_name": "hoang",
      "phone_number": "0972868875"
    }
  ]
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": {
    "id": "9e749e68-142f-4587-a3b1-70279c30b5c2",
    "name": "Nguyen Van Hoang",
    "gender": null,
    "emails": [],
    "phone_numbers": [
      "0903924956"
    ],
    "date_of_birth": "1995-02-01",
    "reward_point": 0,
    "is_discount_by_level": true,
    "tags": [],
    "is_block": false,
    "assigned_user_id": "e4cec6de-96fa-4c16-9523-07910ddfee8e",
    "level_id": null,
    "notes": [],
    "shop_customer_address": [
      {
        "id": "deeb419a-e7b6-42fd-9684-52ec6a72a41a",
        "country_code": 84,
        "province_id": null,
        "district_id": null,
        "commune_id": null,
        "address": null,
        "full_address": null,
        "full_name": null,
        "phone_number": "0903924956"
      }
    ],
    "order_count": 0,
    "purchased_amount": 0,
    "succeed_order_count": 0,
    "last_order_at": "2024-05-16T17:00:00Z",
    "conversation_link": null,
    "referral_code": "gqo7ulKf",
    "fb_id": null,
    "customer_id": "5b717afb-1856-48c9-9b6e-b8ac9db7d520"
  }
}
```

## Customer detail

`GET /shops/{SHOP_ID}/customers/{CUSTOMER_ID}`

Get detail information of a customer

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `CUSTOMER_ID` | path | string | yes | Customer ID |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "id": "b0110315-b102-436b-8b3b-ed8d16740327",
      "name": "Trần Văn Hoàng",
      "gender": "male",
      "emails": [
        "thudo@gmail.com"
      ],
      "phone_numbers": [
        "0999999999"
      ],
      "date_of_birth": "1999-09-01",
      "reward_point": 10,
      "is_discount_by_level": true,
      "tags": [],
      "is_block": false,
      "assigned_user_id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
      "level_id": null,
      "notes": [],
      "shop_customer_address": [
        {
          "id": "0fefd213-7d0c-4d5b-bdbf-35694da80857",
          "country_code": null,
          "province_id": "101",
          "district_id": "10101",
          "commune_id": null,
          "address": "lê văn lương",
          "full_address": "lê văn lương, Quận Ba Đình, Hà Nội",
          "full_name": "test",
          "phone_number": "0999999999"
        }
      ],
      "order_count": 108,
      "purchased_amount": 0,
      "succeed_order_count": 8,
      "last_order_at": "2020-04-01T10:18:41Z",
      "conversation_link": "https://pancake.vn/2284322048329488?customer_id=fc0dda4f-8d2a-4e70-a34a-7a6a434c6475",
      "referral_code": "1nw4geGA",
      "fb_id": null,
      "customer_id": "96a8e283-3fba-492e-a35a-970f72a30a02",
      "pages_customers": [
        {
          "id": 256469571170000,
          "name": "Clonners",
          "platform": "facebook"
        }
      ]
    }
  ]
}
```

## Update customer

`PUT /shops/{SHOP_ID}/customers/{CUSTOMER_ID}`

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `CUSTOMER_ID` | path | string | yes | Customer ID |

### Request body

Request body containing customer information to update

- `customer` (Customer, required): 
  - `id` (string): Customer ID
  - `name` (string): Full name
  - `gender` (string): Gender
  - `emails` (string[]): Email addresses
  - `phone_numbers` (string[]): Phone numbers
  - `pages_customers` (object[]): Customer's linked pages
  - `date_of_birth` (string (date)): Date of birth
  - `reward_point` (number): Reward point
  - `is_discount_by_level` (boolean): Discount based on level
  - `tags` (string[]): Customer tags
  - `is_block` (boolean): Block customer
  - `assigned_user_id` (string): Assigned employee ID
  - `level_id` (string): Customer level ID
  - `notes` (object[]): Customer notes
  - `shop_customer_address` (object[]): Customer addresses
  - `order_count` (integer): Order count
  - `purchased_amount` (integer): Purchased amount
  - `succeed_order_count` (integer): Succeed order count
  - `last_order_at` (string (date-time)): Last order at
  - `conversation_link` (string (uri)): Conversation link
  - `referral_code` (string): Referral code
  - `fb_id` (string): Facebook ID
  - `customer_id` (string): Customer ID

```json
{
  "customer": {
    "name": "Nguyễn Thị Hằng",
    "gender": "female",
    "emails": [
      "pancake@gmail.com",
      "hoang@gmail.com"
    ],
    "phone_numbers": [
      "0983925966"
    ],
    "date_of_birth": "1995-03-04",
    "reward_point": 20,
    "is_discount_by_level": false,
    "tags": [
      "Hay hoàn"
    ],
    "is_block": false,
    "assigned_user_id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
    "level_id": "f8dced06-965d-4070-a765-dd8268373f1e",
    "notes": [
      {
        "id": "8a6f5380-4674-44e9-aaf2-40d898d460f5",
        "message": "Khách hàng thân thiết",
        "images": [
          {
            "url": "https://content.pancake.vn/user-content-dev2.pancake.vn/2023/9/6/655ae9172118ba9ffde16fa129a7001a392d1fff.png"
          }
        ]
      }
    ],
    "shop_customer_address": [
      {
        "id": "df631f21-3841-4d1c-8204-b85a7ecfce0c",
        "country_code": 84,
        "province_id": "101",
        "district_id": "10113",
        "commune_id": "1011309",
        "address": "190 Cầu Giấy",
        "full_name": "sơn",
        "phone_number": "0972868874"
      }
    ],
    "order_count": 7,
    "purchased_amount": 1000000
  }
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true
}
```

## Customer reward point history

`GET /shops/{SHOP_ID}/customers/point_logs`

Get reward point history for a customer

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `shop_customer_id` | query | string | yes | Customer ID |
| `page_size` | query | integer |  | Page size |
| `page_number` | query | integer |  | Page number |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "amount": 10,
      "creator": {
        "id": "8fbe2a6f-b0b2-4227-a698-19d18c43f7c8",
        "name": "Hoang Anh",
        "fb_id": "2042723249341651",
        "avatar_url": null
      },
      "current_point": 100,
      "inserted_at": "2024-01-01T00:00:00Z",
      "note": "Tích điểm từ đơn hàng"
    }
  ]
}
```

## Create promotions by customer

`POST /shops/{SHOP_ID}/promotion_advance/create_multi`

Create promotions for specific customers

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |

### Request body

Request body containing promotion information to create for customers

- `promotion_advance` (object, required): 
  - `promotion` (object, required): 
  - `shop_customer_ids` (string[], required): Customer IDs to apply

```json
{
  "promotion_advance": {
    "promotion": {
      "start_time": "2024-09-30T04:58:30.020Z",
      "end_time": "2024-10-30T04:58:30.020Z",
      "warehouse_ids": [],
      "customer_tags": [],
      "type": "discount_by_coupon_id",
      "is_activated": true,
      "promo_code_info": {
        "discount": 5,
        "is_percent": true,
        "max_discount_by_percent": 100000,
        "disable": false,
        "order_price_min": 2000000,
        "order_price_max": 3000000,
        "no_applied_products_in_other_promotions": true,
        "discount_after_other_discount": true
      }
    },
    "shop_customer_ids": [
      "a8c1113d-55c2-4f7e-b33a-d4ecd76668fd"
    ]
  }
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true
}
```

## List of notes

`GET /shops/{SHOP_ID}/customers/{CUSTOMER_ID}/load_customer_notes`

Get list of customer notes

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `CUSTOMER_ID` | path | string | yes | Customer ID |

### Responses

- `200` Success (object)

```json
{
  "customer_notes": [
    {
      "notes": [
        {
          "id": "8a6f5380-4674-44e9-aaf2-40d898d460f5",
          "message": "Khách hàng thân thiết",
          "images": [
            {
              "url": "https://content.pancake.vn/user-content-dev2.pancake.vn/2023/9/6/655ae9172118ba9ffde16fa129a7001a392d1fff.png"
            }
          ],
          "created_at": 1693987200,
          "updated_at": 1693987200,
          "order_id": "116947",
          "created_by": {
            "uid": "cee3c05e-5f85-43c4-b27e-889b99c50097",
            "fb_id": "377936050731194",
            "fb_name": "Vũ Sơn"
          },
          "edit_history": []
        }
      ]
    }
  ]
}
```

## Add note

`POST /shops/{SHOP_ID}/customers/{CUSTOMER_ID}/create_note`

Add a note to customer

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `CUSTOMER_ID` | path | string | yes | Customer ID |

### Request body

Request body containing customer note information

- `conversation_id` (string): Conversation ID
- `page_id` (string): Page ID
- `message` (string): Note content
- `images` (object[]): Note image information
  - `url` (string (uri)): Image URL
  - `preview_url` (string (uri)): Preview URL
  - `name` (string): Image name
  - `image_data` (object): 
- `order_id` (integer): Order ID

```json
{
  "conversation_id": "117967746266487_9306266852780716",
  "page_id": "117967746266487",
  "message": "khách hàng mua nhiều lần",
  "images": [
    {
      "image_data": {
        "height": 225,
        "width": 225
      },
      "name": "iship thai.jpeg",
      "preview_url": "https://content.pancake.vn/user-content-dev2.pancake.vn/2025/2/25/2488ecb12514520d9828390f695abc9db69a1452.jpg",
      "url": "https://content.pancake.vn/user-content-dev2.pancake.vn/2025/2/25/2488ecb12514520d9828390f695abc9db69a1452.jpg"
    }
  ],
  "order_id": 116947
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true
}
```

## Customer level list

`GET /shops/{SHOP_ID}/customer_levels`

Get list of customer levels

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `search` | query | string |  | Customer level name |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "id": "84fdef8b-8e4b-44e7-8d61-8553ee7f5833",
      "name": "cap 1",
      "color_customer_level": "#87d068",
      "discount": 5,
      "discount_type": 3,
      "shop_id": 20,
      "upgrade_by_order_count": 10,
      "upgrade_by_point": 100,
      "upgrade_by_total_purchase": 30000000
    }
  ]
}
```