Meisei

    Loyalty activity

    GET /loyalty-activity

    List loyalty activity, newest first. Every entry is part of the append-only ledger: points earns, spends, manual adjustments, revocations and expiries. Supports search, filtering and cursor pagination.

    Requires the loyalty:read permission.

    Query parameters

    limitnumber

    The number of records to return.

    cursorstring

    A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

    sortcreatedAt | -createdAt | amount | -amount

    The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

    searchstring

    A free-text search term. Every word has to match, from the start of a word, in any order and ignoring case and accents, against the record's most identifying fields. Combined with filter using AND.

    filterstring

    A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, type, loyaltyMembershipId, amount, revokeTransactionId, createdAt, customer.id, customer.email, customer.firstName, customer.lastName, customer.metadata, customer.emailOptOut, customer.emailOptOutSource, customer.createdAt, rule.id, rule.name. See Filtering for the syntax.

    includestring

    A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: customer, rule, membership.

    Request
    curl \
  "https://your-store.meisei.app/api/loyalty-activity" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "id": "A4Ws1igz",
      "type": "points",
      "loyaltyMembershipId": "A4Ws1igz",
      "loyaltyRuleId": "A4Ws1igz",
      "amount": 0,
      "balanceAfter": 0,
      "details": "...",
      "revokeTransactionId": "A4Ws1igz",
      "eventKey": "string",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "customer": {
        "id": "...",
        "email": "...",
        "phone": "...",
        "firstName": "...",
        "lastName": "...",
        "country": "...",
        "metadata": "...",
        "notes": "...",
        "emailOptOut": "...",
        "emailOptOutAt": "...",
        "emailOptOutSource": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "rule": {
        "id": "...",
        "name": "...",
        "section": "..."
      },
      "membership": {
        "id": "...",
        "customerId": "...",
        "loyaltyProgramId": "...",
        "loyaltyTierId": "...",
        "tierAssignedManually": "...",
        "tierAttainedAt": "...",
        "leftAt": "...",
        "createdAt": "...",
        "updatedAt": "..."
      }
    }
  ],
  "nextCursor": "string"
}

    POST /loyalty-activity/adjustments

    Manually adjust a member's points balance, up or down, with a required reason stored on the entry. A deduction may push the balance below zero, for example when correcting fraud. Triggers the loyaltyTransaction.created webhook.

    Requires the loyalty:write permission.

    Body parameters

    loyaltyMembershipIdstringrequired

    The loyalty membership to adjust.

    amountintegerrequired

    The points to add (positive) or deduct (negative).

    reasonstringrequired

    Why the balance was adjusted. Stored on the activity entry.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-activity/adjustments" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "loyaltyMembershipId": "string",
  "amount": 0,
  "reason": "string"
}'
    Response
    {
  "id": "A4Ws1igz",
  "type": "points",
  "loyaltyMembershipId": "A4Ws1igz",
  "loyaltyRuleId": "A4Ws1igz",
  "amount": 0,
  "balanceAfter": 0,
  "details": "...",
  "revokeTransactionId": "A4Ws1igz",
  "eventKey": "string",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "customer": {
    "id": "A4Ws1igz",
    "email": "user@example.com",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "rule": {
    "id": "A4Ws1igz",
    "name": "string",
    "section": "rules"
  },
  "membership": {
    "id": "A4Ws1igz",
    "customerId": "A4Ws1igz",
    "loyaltyProgramId": "A4Ws1igz",
    "loyaltyTierId": "A4Ws1igz",
    "tierAssignedManually": true,
    "tierAttainedAt": "2025-01-15T09:30:00Z",
    "leftAt": "2025-01-15T09:30:00Z",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  }
}

    POST /loyalty-activity/bulk-expire

    Expire outstanding points in bulk, for example everything earned in a retired currency or before a cutoff date. For each member and currency with matching earns, an offsetting expiry transaction is appended so the balance math stays intact, clamped so no balance goes below zero. Omitting the filter considers every transaction in the organization.

    Requires the loyalty:write permission.

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

    Query parameters

    filterstring

    A JSON-encoded filter document selecting the transactions to expire, for example points earned before a cutoff date. Omit it and every transaction in the organization is considered. See Filtering for the syntax.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-activity/bulk-expire" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "count": 0,
  "amountExpired": 0
}

    POST /loyalty-activity/{id}/revoke

    Reverse a points entry by appending a compensating entry of the opposite amount, linked through revokeTransactionId. Only points entries that are not themselves revocations, have not already been revoked and did not pay for a reward can be revoked; anything else returns a 409. To give back the points a reward was claimed with, revoke the reward instead. Revoking an earn the member already spent may push the balance below zero. Triggers the loyaltyTransaction.created webhook.

    Requires the loyalty:write permission.

    Path parameters

    idstringrequired

    The ID of the points entry to revoke.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-activity/A4Ws1igz/revoke" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "A4Ws1igz",
  "type": "points",
  "loyaltyMembershipId": "A4Ws1igz",
  "loyaltyRuleId": "A4Ws1igz",
  "amount": 0,
  "balanceAfter": 0,
  "details": "...",
  "revokeTransactionId": "A4Ws1igz",
  "eventKey": "string",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "customer": {
    "id": "A4Ws1igz",
    "email": "user@example.com",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "rule": {
    "id": "A4Ws1igz",
    "name": "string",
    "section": "rules"
  },
  "membership": {
    "id": "A4Ws1igz",
    "customerId": "A4Ws1igz",
    "loyaltyProgramId": "A4Ws1igz",
    "loyaltyTierId": "A4Ws1igz",
    "tierAssignedManually": true,
    "tierAttainedAt": "2025-01-15T09:30:00Z",
    "leftAt": "2025-01-15T09:30:00Z",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  }
}

    GET /loyalty-activity/{id}

    Get a single loyalty activity entry by ID.

    Requires the loyalty:read permission.

    Path parameters

    idstringrequired

    The ID of the activity entry.

    Query parameters

    includestring

    A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: customer, rule, membership.

    Request
    curl \
  "https://your-store.meisei.app/api/loyalty-activity/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "A4Ws1igz",
  "type": "points",
  "loyaltyMembershipId": "A4Ws1igz",
  "loyaltyRuleId": "A4Ws1igz",
  "amount": 0,
  "balanceAfter": 0,
  "details": "...",
  "revokeTransactionId": "A4Ws1igz",
  "eventKey": "string",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "customer": {
    "id": "A4Ws1igz",
    "email": "user@example.com",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "rule": {
    "id": "A4Ws1igz",
    "name": "string",
    "section": "rules"
  },
  "membership": {
    "id": "A4Ws1igz",
    "customerId": "A4Ws1igz",
    "loyaltyProgramId": "A4Ws1igz",
    "loyaltyTierId": "A4Ws1igz",
    "tierAssignedManually": true,
    "tierAttainedAt": "2025-01-15T09:30:00Z",
    "leftAt": "2025-01-15T09:30:00Z",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  }
}