Meisei

    Loyalty events

    GET /loyalty-events

    List the custom events your systems have reported, newest first by default. Filter by name, by properties.<name>, or by the customer through customer.id or customer.email. 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.

    sortoccurredAt | -occurredAt | createdAt | -createdAt

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

    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, name, value, properties, idempotencyKey, occurredAt, createdAt, customer.id, customer.email, customer.firstName, customer.lastName, customer.metadata, customer.emailOptOut, customer.emailOptOutSource, customer.createdAt. 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.

    Request
    curl \
  "https://your-store.meisei.app/api/loyalty-events" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "id": "A4Ws1igz",
      "customerId": "A4Ws1igz",
      "name": "string",
      "value": 0,
      "properties": "...",
      "idempotencyKey": "string",
      "occurredAt": "2025-01-15T09:30:00Z",
      "createdAt": "2025-01-15T09:30:00Z",
      "customer": {
        "id": "...",
        "email": "...",
        "phone": "...",
        "firstName": "...",
        "lastName": "...",
        "country": "...",
        "metadata": "...",
        "notes": "...",
        "emailOptOut": "...",
        "emailOptOutAt": "...",
        "emailOptOutSource": "...",
        "createdAt": "...",
        "updatedAt": "..."
      }
    }
  ],
  "nextCursor": "string"
}

    POST /loyalty-events

    Report something your own systems saw about a customer, as a named event with an optional value and properties. Every rule whose trigger listens for the name decides what the customer earns: it can require conditions on the properties, fire on every Nth event, or cap how often it fires per day, week or month. The event is recorded even when no rule listens for it yet. Rules run on a queue rather than inline, so a 202 means the event was recorded, not that anything was awarded yet. Sending the same idempotencyKey again for the same customer returns the original event and awards nothing a second time. Programs that are paused are reported back rather than queued.

    Requires the loyalty:write permission.

    Body parameters

    namestringrequired

    The event's name, such as review.written. Letters, digits, periods, underscores, colons and hyphens, up to 100 characters.

    customerIdstring

    The customer the event is about. Send this or customerEmail, not both.

    customerEmailstring (email)

    The email address of the customer the event is about, as Meisei knows them. Send this or customerId, not both.

    valueinteger

    How many units this event is worth, for rules whose trigger scales with it. Leave it out and the rule's own default applies. Rules that do not scale ignore it.

    propertiesobject

    Free-form facts about the event, as a flat object of strings, numbers and booleans, such as { "rating": 5, "channel": "store" }. Rules can require conditions on them.

    idempotencyKeystring

    Your own identifier for this event, such as the id of the record that caused it. Sending it again for the same customer returns the event already recorded and awards nothing a second time. Leave it out and every call counts separately.

    createCustomerboolean

    Create the customer when customerEmail is an address Meisei has never seen. Off by default, so a mistyped address is a 404 rather than a new record.

    occurredAtstring (date-time)

    When the event happened, as an ISO 8601 timestamp. Defaults to now.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-events" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "customerId": "string",
  "customerEmail": "user@example.com",
  "value": 0,
  "properties": "...",
  "idempotencyKey": "string",
  "createCustomer": true,
  "occurredAt": "2025-01-15T09:30:00Z"
}'
    Response
    {
  "event": {
    "id": "A4Ws1igz",
    "customerId": "A4Ws1igz",
    "name": "string",
    "value": 0,
    "properties": "...",
    "idempotencyKey": "string",
    "occurredAt": "2025-01-15T09:30:00Z",
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "duplicate": true,
  "loyaltyProgramIds": ["A4Ws1igz"],
  "pausedLoyaltyProgramIds": ["A4Ws1igz"]
}

    GET /loyalty-events/{id}

    Get a single custom event by ID.

    Requires the loyalty:read permission.

    Path parameters

    idstringrequired

    The ID of the event.

    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.

    Request
    curl \
  "https://your-store.meisei.app/api/loyalty-events/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "A4Ws1igz",
  "customerId": "A4Ws1igz",
  "name": "string",
  "value": 0,
  "properties": "...",
  "idempotencyKey": "string",
  "occurredAt": "2025-01-15T09:30:00Z",
  "createdAt": "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"
  }
}