**版本：202607**

# 增加积分

**POST** `/openapi/2026-07/loyalty/members/points/earn`

为指定会员增加积分，支持批量操作

## 请求

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `operate_type` string (required)

  会员定位方式:member\_id 或 email
- `operate_values` string[] (required)

  待加分会员的定位值列表,单次最多 200 个
- `points` int64 (required)

  加分数量,必须为正数
- `reason` string

  业务原因,会写入积分变更记录
- `idempotency_key` string

  批次级幂等 ID,1 小时窗口内同 key 回放首次响应
- `point_expired_setting` object

  积分过期配置覆盖,不传则使用店铺全局配置

  - `is_expired` boolean

    积分是否过期
  - `expired_method` string

    过期方式:after\_x\_months / on\_specific\_date / ...
  - `day` int32

    过期规则的天
  - `month` int32

    过期规则的月
  - `protect_enabled` boolean

    是否开启过期保护
  - `protect_days` int32

    保护天数
  - `use_global_config` boolean

    是否使用店铺全局配置
- `send_email` boolean

  是否给会员发送积分变动通知邮件

```json
{
  "operate_type": "string",
  "operate_values": [
    "string"
  ],
  "points": 0,
  "reason": "string",
  "idempotency_key": "string",
  "point_expired_setting": {
    "is_expired": true,
    "expired_method": "string",
    "day": 0,
    "month": 0,
    "protect_enabled": true,
    "protect_days": 0,
    "use_global_config": true
  },
  "send_email": true
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `success_count` int32

    成功条数
  - `failed_count` int32

    失败条数
  - `results` object[]

    积分变更结果列表

    *   Array \[

    - `member_id` string

      服务端解析出的会员 ID
    - `transaction_id` string

      积分流水唯一 ID
    - `change_value` int64

      本次变动值,加分为正
    - `occurred_at` string

      变动生效时间,ISO-8601
    - `expiration_at` int64

      本次加分最终生效的过期时间,Unix 秒(protojson 序列化为字符串)。0 表示永久不过期
    *   \]
  - `failed_values` string[]

    失败的会员定位值列表

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "success_count": 0,
    "failed_count": 0,
    "results": [
      {
        "member_id": "string",
        "transaction_id": "string",
        "change_value": 0,
        "occurred_at": "string",
        "expiration_at": 0
      }
    ],
    "failed_values": [
      "string"
    ]
  }
}
```