> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loyalty Card Events

> JSON Schemas for the events published when a customer's loyalty card is created, imported, changes state or is deleted.

<Warning>
  **Constraints**

  Deleting a customer removes all their loyalty cards without publishing Loyalty Card Deleted. Treat [Member Deleted](/integration/external-integrations/events/customer-events) as the deletion of every card that customer had.

  An import publishes Loyalty Card Imported only for cards that did not exist yet. A card that already exists publishes Loyalty Card State Changed, and only if the import changes its state.

  Loyalty Card State Changed is published only when the state actually changes. Besides a card update, it is published when creating a card replaces the customer's active cards, when creating a card reactivates an inactive one, and when a customer is deactivated. Activating a customer does not reactivate their cards.

  The `EventId` of these events contains a random part, so a redelivered event carries a new `EventId`. Don't use it alone for idempotent processing.
</Warning>

Published when a customer's loyalty card changes. A loyalty card is the card a customer identifies with at the till — not a challenge card, which is covered by [Card Events](/integration/external-integrations/events/card-events). Every payload carries `CustomerId`, `MemberId` and `LoyaltyCardId`; `CustomerId` equals `MemberId`.

## Field reference

Field definitions match the loyalty card models used by the Members endpoints. See [Members](/api-reference/loyalty-and-membership/members) in the API Reference.

| Event | Triggering endpoint |
| - | - |
| Loyalty Card Created | `POST /v1/loyalty-cards` — Creates a new loyalty card |
| Loyalty Card Imported | `POST /v1/loyalty-cards/import` — Imports or updates loyalty cards |
| Loyalty Card State Changed | `PUT /v1/loyalty-cards/{cardId}` — Updates loyalty card properties |
| Loyalty Card Deleted | `DELETE /v1/loyalty-cards/{cardId}` — Deletes a loyalty card by ID |

The mobile app equivalents (`POST /mobile-app/v1/loyalty-cards` and `PUT /mobile-app/v1/loyalty-cards/{cardId}`) and the admin portal's card actions emit the same events. `POST /v1/loyalty-cards/import/data-import` behaves like `/import`. `POST /v1/loyalty-cards/{memberId}/deactivate` and `PUT /v1/members/{memberId}/deactivate` emit Loyalty Card State Changed for every card they deactivate.

## Schemas

<Tabs>
  <Tab title="Loyalty Card Created">
    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "LoyaltyCardId": { "type": "string" },
        "MemberId": { "type": "string" },
        "Type": { "type": "string", "enum": ["Physical", "Virtual"] },
        "Author": { "$ref": "#/$defs/author" },
        "Timestamp": { "type": "string", "format": "date-time", "description": "When the card was created." },
        "EventId": { "type": "string", "description": "Composed as LoyaltyCardCreated-{Timestamp}-{random}." },
        "CustomerId": { "type": "string" }
      },
      "$defs": {
        "author": {
          "type": "object",
          "properties": {
            "Id": { "type": "string" },
            "FullName": { "type": "string" }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Loyalty Card Imported">
    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "LoyaltyCardId": { "type": "string" },
        "MemberId": { "type": "string" },
        "Type": { "type": "string", "enum": ["Physical", "Virtual"] },
        "State": { "type": "string", "enum": ["Inactive", "Active"] },
        "Author": { "$ref": "#/$defs/author" },
        "Timestamp": { "type": "string", "format": "date-time", "description": "The card's creation time from the import request, or the import time when the request has none." },
        "EventId": { "type": "string", "description": "Composed as LoyaltyCardImported-{Timestamp}-{random}." },
        "CustomerId": { "type": "string" }
      },
      "$defs": {
        "author": {
          "type": "object",
          "description": "Always 'member' for Id and FullName on imports.",
          "properties": {
            "Id": { "type": "string" },
            "FullName": { "type": "string" }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Loyalty Card State Changed">
    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "LoyaltyCardId": { "type": "string" },
        "MemberId": { "type": "string" },
        "OldValue": { "type": "string", "enum": ["Inactive", "Active"] },
        "NewValue": { "type": "string", "enum": ["Inactive", "Active"] },
        "Author": { "$ref": "#/$defs/author" },
        "Timestamp": { "type": "string", "format": "date-time" },
        "EventId": { "type": "string", "description": "Composed as LoyaltyCardStateChanged-{Timestamp}-{random}." },
        "CustomerId": { "type": "string" }
      },
      "$defs": {
        "author": {
          "type": "object",
          "properties": {
            "Id": { "type": "string" },
            "FullName": { "type": "string" }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Loyalty Card Deleted">
    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "LoyaltyCardId": { "type": "string" },
        "MemberId": { "type": "string" },
        "Type": { "type": "string", "enum": ["Physical", "Virtual"] },
        "Author": { "$ref": "#/$defs/author" },
        "Timestamp": { "type": "string", "format": "date-time", "description": "When the card was deleted." },
        "EventId": { "type": "string", "description": "Composed as LoyaltyCardDeleted-{Timestamp}-{random}." },
        "CustomerId": { "type": "string" }
      },
      "$defs": {
        "author": {
          "type": "object",
          "properties": {
            "Id": { "type": "string" },
            "FullName": { "type": "string" }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.