Meisei

    Loyalty history

    POST /loyalty-history

    Write a member's loyalty history from the platform you are leaving: earns, spends and adjustments, each filed under the time it happened. Rolling tier windows and monthly activity then see real history instead of starting from zero. Entries may arrive in any order and may predate the member joining; the balance and every entry's running total are put back in order before the call returns. Sending an externalId again writes nothing a second time. A member who already has an opening balance from a member import has it reduced by what the history explains, so nothing is counted twice.

    Requires the loyalty:write permission.

    Costs 10 rate limit tokens instead of the usual one. See Rate limits.

    Body parameters

    customerEmailstring (email)required

    The customer the history belongs to, as Meisei knows them. Import your customers first: an address Meisei has never seen is a 404.

    loyaltyProgramIdstring

    The program the history belongs to. Leave it out and the organization's only program is used, which fails when there is more than one.

    entriesobject[]required

    The entries to write, up to 500 per call. They may arrive in any order and may predate the member joining. Send the whole of a member's history in one call where you can, so the balance settles once.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-history" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerEmail": "user@example.com",
  "loyaltyProgramId": "string",
  "entries": [
    {
      "externalId": "string",
      "occurredAt": "2025-01-15T09:30:00Z",
      "amount": 0,
      "kind": "earn",
      "reason": "string"
    }
  ]
}'
    Response
    {
  "customerId": "A4Ws1igz",
  "loyaltyProgramId": "A4Ws1igz",
  "loyaltyMembershipId": "A4Ws1igz",
  "createdCount": 0,
  "duplicateCount": 0,
  "balance": 0,
  "loyaltyTierId": "A4Ws1igz",
  "openingAdjustment": {
    "status": "none",
    "amount": 0
  },
  "entries": [
    {
      "externalId": "string",
      "status": "created",
      "loyaltyTransactionId": "A4Ws1igz",
      "occurredAt": "2025-01-15T09:30:00Z",
      "amount": 0,
      "balanceAfter": 0
    }
  ]
}