Earn points

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

Add points to one or more members

Request

application/json

Body

Bodyrequired

operate_typestringrequired

Member locator type: member_id or email

operate_valuesstring[]required

Locator values to credit. Up to 200 per request

pointsint64required

Points to add. Must be positive

reasonstring

Business reason stored with the points change record

idempotency_keystring

Batch-level idempotency key. Same key within one hour replays the first response

point_expired_setting object

Points expiration override. When omitted, store global setting applies

is_expiredboolean

Whether points expire

expired_methodstring

Expiry method: after_x_months / on_specific_date / ...

dayint32

Day component of the expiry rule

monthint32

Month component of the expiry rule

protect_enabledboolean

Whether expiry protection is enabled

protect_daysint32

Protection days

use_global_configboolean

Whether to use the store global config

send_emailboolean

Whether to send a points-change notification email to the member

Example

{
  "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
}

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

success_countint32

Number of successful items

failed_countint32

Number of failed items

results object[]

Points change results

Array [

member_idstring

Resolved member ID

transaction_idstring

Points transaction ID

change_valueint64

Change amount. Positive for earn

occurred_atstring

Effective time, ISO-8601

expiration_atint64

Final effective expiration time of the points earned in this operation, Unix seconds (serialized as a protojson string). 0 means permanent

]

failed_valuesstring[]

Locator values that failed

Example

{
  "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"
    ]
  }
}