Loyalty programs

GET `/loyalty-programs`

List the organization's loyalty programs, alphabetically by default. Pass include=counts for what each program holds, which is what a deletion would take with it.

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.

sortname | -name | createdAt | -createdAt

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

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: counts.

filterstring

A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, name, createdAt. See Filtering for the syntax.

Request

curl \
  "https://your-store.meisei.app/api/loyalty-programs" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getLoyaltyPrograms } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getLoyaltyPrograms()

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

page = meisei.loyalty_programs.list

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

page = meisei.loyalty_programs.list()

Response

{
  "data": [
    {
      "id": "A4Ws1igz",
      "name": "string",
      "autoMembership": "off",
      "settings": {
        "previousPointsNames": "..."
      },
      "sectionsEnabled": {
        "rules": "...",
        "offers": "..."
      },
      "pointsNames": {
        "singular": "...",
        "plural": "..."
      },
      "pointsExpiresAfterDays": 0,
      "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
      "rewardsExpireAfterDays": 0,
      "expiringSoonDays": 0,
      "pausedAt": "2025-01-15T09:30:00Z",
      "publishedAt": "2025-01-15T09:30:00Z",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "counts": {
        "rules": "...",
        "tiers": "...",
        "members": "...",
        "rewards": "...",
        "sites": "..."
      }
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the loyalty program.",
            "idCodec": "sqid"
          },
          "name": {
            "type": "string",
            "description": "The program's display name, shown to members."
          },
          "autoMembership": {
            "type": "string",
            "enum": ["off", "onFirstActivity"],
            "description": "When customers are enrolled in the program automatically. `off` means they join only when enrolled explicitly; `onFirstActivity` enrolls them the first time they do something the program rewards."
          },
          "settings": {
            "type": "object",
            "properties": {
              "previousPointsNames": {
                "default": null,
                "description": "The names the points had before they were switched off, kept so switching them back on restores them. Null when points have never been switched off.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "singular": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The name of one point, such as `point`."
                      },
                      "plural": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The name of several points, such as `points`."
                      }
                    },
                    "required": ["singular", "plural"],
                    "additionalProperties": false,
                    "description": "Unit names a balance is composed from, for example `12 points`."
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": ["previousPointsNames"],
            "additionalProperties": false,
            "description": "Program-level configuration: the points names kept from before points were switched off."
          },
          "sectionsEnabled": {
            "type": "object",
            "properties": {
              "rules": {
                "type": "boolean",
                "description": "Whether the ways-to-earn section is shown to members."
              },
              "offers": {
                "type": "boolean",
                "description": "Whether the offers section is shown to members."
              }
            },
            "required": ["rules", "offers"],
            "additionalProperties": false,
            "description": "Which optional sections members see in the loyalty widget."
          },
          "pointsNames": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "singular": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The name of one point, such as `point`."
                  },
                  "plural": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The name of several points, such as `points`."
                  }
                },
                "required": ["singular", "plural"],
                "additionalProperties": false,
                "description": "Unit names a balance is composed from, for example `12 points`."
              },
              {
                "type": "null"
              }
            ],
            "description": "What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them."
          },
          "pointsExpiresAfterDays": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Each earn expires this many days after it happened. Null means earns never age out. When `pointsBalancesExpireAt` is also set, the earlier of the two applies."
          },
          "pointsBalancesExpireAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When `pointsExpiresAfterDays` is also set, the earlier of the two applies."
          },
          "rewardsExpireAfterDays": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this."
          },
          "expiringSoonDays": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out."
          },
          "pausedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the program was paused. While it is set the program earns nothing, and members keep their balances, rewards and history."
          },
          "publishedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the program was published. Null means it is still a draft: no shopper can see it, join it or earn in it, and only a preview link reaches it. Publishing cannot be undone, so pause a program you want to take down."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the program was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the program was last changed."
          },
          "counts": {
            "type": "object",
            "properties": {
              "rules": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Earning and redemption rules in the program."
              },
              "tiers": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Tiers, archived ones included."
              },
              "members": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Members enrolled in the program."
              },
              "rewards": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Rewards the program has issued, in any state."
              },
              "sites": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "description": "Sites the program is currently attached to."
              }
            },
            "required": ["rules", "tiers", "members", "rewards", "sites"],
            "additionalProperties": false,
            "description": "What belongs to the program, and so what a deletion takes with it. Each count is a separate query."
          }
        },
        "required": [
          "id",
          "name",
          "autoMembership",
          "settings",
          "sectionsEnabled",
          "pointsNames",
          "pointsExpiresAfterDays",
          "pointsBalancesExpireAt",
          "rewardsExpireAfterDays",
          "expiringSoonDays",
          "pausedAt",
          "publishedAt",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The page of records, in the requested sort order."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass this back as `cursor` to fetch the next page. Null once the last page has been returned."
    }
  },
  "required": ["data", "nextCursor"],
  "additionalProperties": false
}

POST `/loyalty-programs`

Create a loyalty program. Name its points and it can hand them out, hold balances and offer things to spend them on; leave pointsNames out and it runs on coupons alone. The program is attached to every site the organization has, and to any site added later. It starts as a draft, so nothing is visible to shoppers until you call POST /loyalty-programs/{id}/publish. Triggers the loyaltyProgram.created webhook.

Requires the loyalty:write permission.

Body parameters

namestringrequired

The program's display name, shown to members.

autoMembershipoff | onFirstActivity

When customers are enrolled in the program automatically. off means they join only when enrolled explicitly; onFirstActivity enrolls them the first time they do something the program rewards.

sectionsEnabledobject

The sections to show. Anything you leave out starts switched on.

pointsNamesobject | null

What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them.

pointsExpiresAfterDaysinteger | null

Each earn expires this many days after it happened. Null means earns never age out. When pointsBalancesExpireAt is also set, the earlier of the two applies.

pointsBalancesExpireAtstring (date-time) | null

Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When pointsExpiresAfterDays is also set, the earlier of the two applies.

rewardsExpireAfterDaysinteger | null

Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this.

expiringSoonDaysinteger | null

How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-programs" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "autoMembership": "off",
  "sectionsEnabled": {
    "rules": true,
    "offers": true
  },
  "pointsNames": {
    "singular": "string",
    "plural": "string"
  },
  "pointsExpiresAfterDays": 0,
  "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
  "rewardsExpireAfterDays": 0,
  "expiringSoonDays": 0
}'

Request

import { client } from "@meisei/api/admin/client"
import { postLoyaltyPrograms } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postLoyaltyPrograms({
  body: {
    name: "string",
    autoMembership: "off",
    sectionsEnabled: {
      rules: true,
      offers: true,
    },
    pointsNames: {
      singular: "string",
      plural: "string",
    },
    pointsExpiresAfterDays: 0,
    pointsBalancesExpireAt: "2025-01-15T09:30:00Z",
    rewardsExpireAfterDays: 0,
    expiringSoonDays: 0,
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.create(
  name: "string",
  auto_membership: "off",
  sections_enabled: { rules: true, offers: true },
  points_names: { singular: "string", plural: "string" },
  points_expires_after_days: 0,
  points_balances_expire_at: "2025-01-15T09:30:00Z",
  rewards_expire_after_days: 0,
  expiring_soon_days: 0,
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.create(
    name="string",
    auto_membership="off",
    sections_enabled={"rules": True, "offers": True},
    points_names={"singular": "string", "plural": "string"},
    points_expires_after_days=0,
    points_balances_expire_at="2025-01-15T09:30:00Z",
    rewards_expire_after_days=0,
    expiring_soon_days=0,
)

Response

{
  "id": "A4Ws1igz",
  "name": "string",
  "autoMembership": "off",
  "settings": {
    "previousPointsNames": null
  },
  "sectionsEnabled": {
    "rules": true,
    "offers": true
  },
  "pointsNames": {
    "singular": "string",
    "plural": "string"
  },
  "pointsExpiresAfterDays": 0,
  "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
  "rewardsExpireAfterDays": 0,
  "expiringSoonDays": 0,
  "pausedAt": "2025-01-15T09:30:00Z",
  "publishedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the loyalty program.",
      "idCodec": "sqid"
    },
    "name": {
      "type": "string",
      "description": "The program's display name, shown to members."
    },
    "autoMembership": {
      "type": "string",
      "enum": ["off", "onFirstActivity"],
      "description": "When customers are enrolled in the program automatically. `off` means they join only when enrolled explicitly; `onFirstActivity` enrolls them the first time they do something the program rewards."
    },
    "settings": {
      "type": "object",
      "properties": {
        "previousPointsNames": {
          "default": null,
          "description": "The names the points had before they were switched off, kept so switching them back on restores them. Null when points have never been switched off.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "singular": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of one point, such as `point`."
                },
                "plural": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of several points, such as `points`."
                }
              },
              "required": ["singular", "plural"],
              "additionalProperties": false,
              "description": "Unit names a balance is composed from, for example `12 points`."
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": ["previousPointsNames"],
      "additionalProperties": false,
      "description": "Program-level configuration: the points names kept from before points were switched off."
    },
    "sectionsEnabled": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "boolean",
          "description": "Whether the ways-to-earn section is shown to members."
        },
        "offers": {
          "type": "boolean",
          "description": "Whether the offers section is shown to members."
        }
      },
      "required": ["rules", "offers"],
      "additionalProperties": false,
      "description": "Which optional sections members see in the loyalty widget."
    },
    "pointsNames": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "singular": {
              "type": "string",
              "minLength": 1,
              "description": "The name of one point, such as `point`."
            },
            "plural": {
              "type": "string",
              "minLength": 1,
              "description": "The name of several points, such as `points`."
            }
          },
          "required": ["singular", "plural"],
          "additionalProperties": false,
          "description": "Unit names a balance is composed from, for example `12 points`."
        },
        {
          "type": "null"
        }
      ],
      "description": "What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them."
    },
    "pointsExpiresAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Each earn expires this many days after it happened. Null means earns never age out. When `pointsBalancesExpireAt` is also set, the earlier of the two applies."
    },
    "pointsBalancesExpireAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When `pointsExpiresAfterDays` is also set, the earlier of the two applies."
    },
    "rewardsExpireAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this."
    },
    "expiringSoonDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out."
    },
    "pausedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was paused. While it is set the program earns nothing, and members keep their balances, rewards and history."
    },
    "publishedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was published. Null means it is still a draft: no shopper can see it, join it or earn in it, and only a preview link reaches it. Publishing cannot be undone, so pause a program you want to take down."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "autoMembership",
    "settings",
    "sectionsEnabled",
    "pointsNames",
    "pointsExpiresAfterDays",
    "pointsBalancesExpireAt",
    "rewardsExpireAfterDays",
    "expiringSoonDays",
    "pausedAt",
    "publishedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The new program."
}

GET `/loyalty-programs/{id}`

Get a single loyalty program by ID.

Requires the loyalty:read permission.

Path parameters

idstringrequired

The ID of the loyalty program.

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: counts.

Request

curl \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getLoyaltyProgramsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getLoyaltyProgramsById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.retrieve("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.retrieve("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "name": "string",
  "autoMembership": "off",
  "settings": {
    "previousPointsNames": null
  },
  "sectionsEnabled": {
    "rules": true,
    "offers": true
  },
  "pointsNames": {
    "singular": "string",
    "plural": "string"
  },
  "pointsExpiresAfterDays": 0,
  "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
  "rewardsExpireAfterDays": 0,
  "expiringSoonDays": 0,
  "pausedAt": "2025-01-15T09:30:00Z",
  "publishedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "counts": {
    "rules": 0,
    "tiers": 0,
    "members": 0,
    "rewards": 0,
    "sites": 0
  }
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the loyalty program.",
      "idCodec": "sqid"
    },
    "name": {
      "type": "string",
      "description": "The program's display name, shown to members."
    },
    "autoMembership": {
      "type": "string",
      "enum": ["off", "onFirstActivity"],
      "description": "When customers are enrolled in the program automatically. `off` means they join only when enrolled explicitly; `onFirstActivity` enrolls them the first time they do something the program rewards."
    },
    "settings": {
      "type": "object",
      "properties": {
        "previousPointsNames": {
          "default": null,
          "description": "The names the points had before they were switched off, kept so switching them back on restores them. Null when points have never been switched off.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "singular": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of one point, such as `point`."
                },
                "plural": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of several points, such as `points`."
                }
              },
              "required": ["singular", "plural"],
              "additionalProperties": false,
              "description": "Unit names a balance is composed from, for example `12 points`."
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": ["previousPointsNames"],
      "additionalProperties": false,
      "description": "Program-level configuration: the points names kept from before points were switched off."
    },
    "sectionsEnabled": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "boolean",
          "description": "Whether the ways-to-earn section is shown to members."
        },
        "offers": {
          "type": "boolean",
          "description": "Whether the offers section is shown to members."
        }
      },
      "required": ["rules", "offers"],
      "additionalProperties": false,
      "description": "Which optional sections members see in the loyalty widget."
    },
    "pointsNames": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "singular": {
              "type": "string",
              "minLength": 1,
              "description": "The name of one point, such as `point`."
            },
            "plural": {
              "type": "string",
              "minLength": 1,
              "description": "The name of several points, such as `points`."
            }
          },
          "required": ["singular", "plural"],
          "additionalProperties": false,
          "description": "Unit names a balance is composed from, for example `12 points`."
        },
        {
          "type": "null"
        }
      ],
      "description": "What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them."
    },
    "pointsExpiresAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Each earn expires this many days after it happened. Null means earns never age out. When `pointsBalancesExpireAt` is also set, the earlier of the two applies."
    },
    "pointsBalancesExpireAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When `pointsExpiresAfterDays` is also set, the earlier of the two applies."
    },
    "rewardsExpireAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this."
    },
    "expiringSoonDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out."
    },
    "pausedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was paused. While it is set the program earns nothing, and members keep their balances, rewards and history."
    },
    "publishedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was published. Null means it is still a draft: no shopper can see it, join it or earn in it, and only a preview link reaches it. Publishing cannot be undone, so pause a program you want to take down."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was last changed."
    },
    "counts": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Earning and redemption rules in the program."
        },
        "tiers": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Tiers, archived ones included."
        },
        "members": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Members enrolled in the program."
        },
        "rewards": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Rewards the program has issued, in any state."
        },
        "sites": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Sites the program is currently attached to."
        }
      },
      "required": ["rules", "tiers", "members", "rewards", "sites"],
      "additionalProperties": false,
      "description": "What belongs to the program, and so what a deletion takes with it. Each count is a separate query."
    }
  },
  "required": [
    "id",
    "name",
    "autoMembership",
    "settings",
    "sectionsEnabled",
    "pointsNames",
    "pointsExpiresAfterDays",
    "pointsBalancesExpireAt",
    "rewardsExpireAfterDays",
    "expiringSoonDays",
    "pausedAt",
    "publishedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The requested loyalty program."
}

PUT `/loyalty-programs/{id}`

Update a loyalty program's name, enrollment behavior, points, visible sections or paused state. Pausing stops the program earning and leaves every balance, reward and activity entry where it is. Setting pointsNames to null switches points off and keeps the names in settings.previousPointsNames, so they can be sent back to switch points on again. Triggers the loyaltyProgram.updated webhook.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program to update.

Body parameters

namestring

The program's display name.

autoMembershipoff | onFirstActivity

When customers are enrolled in the program automatically. off means they join only when enrolled explicitly; onFirstActivity enrolls them the first time they do something the program rewards.

sectionsEnabledobject

The sections to show or hide. Only the ones you send are changed.

pointsNamesobject | null

What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them.

pointsExpiresAfterDaysinteger | null

Each earn expires this many days after it happened. Null means earns never age out. When pointsBalancesExpireAt is also set, the earlier of the two applies.

pointsBalancesExpireAtstring (date-time) | null

rewardsExpireAfterDaysinteger | null

Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this.

expiringSoonDaysinteger | null

How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out.

pausedboolean

Set to true to pause the program: it stops earning, and members keep their balances, rewards and history. Set to false to start it up again.

Request

curl \
  -X PUT \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "autoMembership": "off",
  "sectionsEnabled": {
    "rules": true,
    "offers": true
  },
  "pointsNames": {
    "singular": "string",
    "plural": "string"
  },
  "pointsExpiresAfterDays": 0,
  "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
  "rewardsExpireAfterDays": 0,
  "expiringSoonDays": 0,
  "paused": true
}'

Request

import { client } from "@meisei/api/admin/client"
import { putLoyaltyProgramsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await putLoyaltyProgramsById({
  path: { id: "A4Ws1igz" },
  body: {
    name: "string",
    autoMembership: "off",
    sectionsEnabled: {
      rules: true,
      offers: true,
    },
    pointsNames: {
      singular: "string",
      plural: "string",
    },
    pointsExpiresAfterDays: 0,
    pointsBalancesExpireAt: "2025-01-15T09:30:00Z",
    rewardsExpireAfterDays: 0,
    expiringSoonDays: 0,
    paused: true,
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.update(
  "A4Ws1igz",
  name: "string",
  auto_membership: "off",
  sections_enabled: { rules: true, offers: true },
  points_names: { singular: "string", plural: "string" },
  points_expires_after_days: 0,
  points_balances_expire_at: "2025-01-15T09:30:00Z",
  rewards_expire_after_days: 0,
  expiring_soon_days: 0,
  paused: true,
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.update(
    "A4Ws1igz",
    name="string",
    auto_membership="off",
    sections_enabled={"rules": True, "offers": True},
    points_names={"singular": "string", "plural": "string"},
    points_expires_after_days=0,
    points_balances_expire_at="2025-01-15T09:30:00Z",
    rewards_expire_after_days=0,
    expiring_soon_days=0,
    paused=True,
)

Response

{
  "id": "A4Ws1igz",
  "name": "string",
  "autoMembership": "off",
  "settings": {
    "previousPointsNames": null
  },
  "sectionsEnabled": {
    "rules": true,
    "offers": true
  },
  "pointsNames": {
    "singular": "string",
    "plural": "string"
  },
  "pointsExpiresAfterDays": 0,
  "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
  "rewardsExpireAfterDays": 0,
  "expiringSoonDays": 0,
  "pausedAt": "2025-01-15T09:30:00Z",
  "publishedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the loyalty program.",
      "idCodec": "sqid"
    },
    "name": {
      "type": "string",
      "description": "The program's display name, shown to members."
    },
    "autoMembership": {
      "type": "string",
      "enum": ["off", "onFirstActivity"],
      "description": "When customers are enrolled in the program automatically. `off` means they join only when enrolled explicitly; `onFirstActivity` enrolls them the first time they do something the program rewards."
    },
    "settings": {
      "type": "object",
      "properties": {
        "previousPointsNames": {
          "default": null,
          "description": "The names the points had before they were switched off, kept so switching them back on restores them. Null when points have never been switched off.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "singular": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of one point, such as `point`."
                },
                "plural": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of several points, such as `points`."
                }
              },
              "required": ["singular", "plural"],
              "additionalProperties": false,
              "description": "Unit names a balance is composed from, for example `12 points`."
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": ["previousPointsNames"],
      "additionalProperties": false,
      "description": "Program-level configuration: the points names kept from before points were switched off."
    },
    "sectionsEnabled": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "boolean",
          "description": "Whether the ways-to-earn section is shown to members."
        },
        "offers": {
          "type": "boolean",
          "description": "Whether the offers section is shown to members."
        }
      },
      "required": ["rules", "offers"],
      "additionalProperties": false,
      "description": "Which optional sections members see in the loyalty widget."
    },
    "pointsNames": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "singular": {
              "type": "string",
              "minLength": 1,
              "description": "The name of one point, such as `point`."
            },
            "plural": {
              "type": "string",
              "minLength": 1,
              "description": "The name of several points, such as `points`."
            }
          },
          "required": ["singular", "plural"],
          "additionalProperties": false,
          "description": "Unit names a balance is composed from, for example `12 points`."
        },
        {
          "type": "null"
        }
      ],
      "description": "What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them."
    },
    "pointsExpiresAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Each earn expires this many days after it happened. Null means earns never age out. When `pointsBalancesExpireAt` is also set, the earlier of the two applies."
    },
    "pointsBalancesExpireAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When `pointsExpiresAfterDays` is also set, the earlier of the two applies."
    },
    "rewardsExpireAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this."
    },
    "expiringSoonDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out."
    },
    "pausedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was paused. While it is set the program earns nothing, and members keep their balances, rewards and history."
    },
    "publishedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was published. Null means it is still a draft: no shopper can see it, join it or earn in it, and only a preview link reaches it. Publishing cannot be undone, so pause a program you want to take down."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "autoMembership",
    "settings",
    "sectionsEnabled",
    "pointsNames",
    "pointsExpiresAfterDays",
    "pointsBalancesExpireAt",
    "rewardsExpireAfterDays",
    "expiringSoonDays",
    "pausedAt",
    "publishedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The updated loyalty program."
}

DELETE `/loyalty-programs/{id}`

Permanently delete a loyalty program. Its rules, tiers, memberships, balances and issued rewards go with it, and the sites it is attached to stop showing it. To stop a program earning without losing any of that, pause it instead. The reason is required and is kept in the audit trail along with who deleted it. Triggers the loyaltyProgram.deleted webhook.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program to delete.

Body parameters

reasonclosing_program | duplicate | replaced | test_data | otherrequired

Why the program is being deleted. Kept in the organization's audit trail.

notestring

Anything worth remembering about the deletion. Required when the reason is other.

Request

curl \
  -X DELETE \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "closing_program",
  "note": "string"
}'

Request

import { client } from "@meisei/api/admin/client"
import { deleteLoyaltyProgramsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteLoyaltyProgramsById({
  path: { id: "A4Ws1igz" },
  body: {
    reason: "closing_program",
    note: "string",
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.delete(
  "A4Ws1igz",
  reason: "closing_program",
  note: "string",
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.delete(
    "A4Ws1igz",
    reason="closing_program",
    note="string",
)

Response

{
  "id": "A4Ws1igz",
  "name": "string",
  "autoMembership": "off",
  "settings": {
    "previousPointsNames": null
  },
  "sectionsEnabled": {
    "rules": true,
    "offers": true
  },
  "pointsNames": {
    "singular": "string",
    "plural": "string"
  },
  "pointsExpiresAfterDays": 0,
  "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
  "rewardsExpireAfterDays": 0,
  "expiringSoonDays": 0,
  "pausedAt": "2025-01-15T09:30:00Z",
  "publishedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the loyalty program.",
      "idCodec": "sqid"
    },
    "name": {
      "type": "string",
      "description": "The program's display name, shown to members."
    },
    "autoMembership": {
      "type": "string",
      "enum": ["off", "onFirstActivity"],
      "description": "When customers are enrolled in the program automatically. `off` means they join only when enrolled explicitly; `onFirstActivity` enrolls them the first time they do something the program rewards."
    },
    "settings": {
      "type": "object",
      "properties": {
        "previousPointsNames": {
          "default": null,
          "description": "The names the points had before they were switched off, kept so switching them back on restores them. Null when points have never been switched off.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "singular": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of one point, such as `point`."
                },
                "plural": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of several points, such as `points`."
                }
              },
              "required": ["singular", "plural"],
              "additionalProperties": false,
              "description": "Unit names a balance is composed from, for example `12 points`."
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": ["previousPointsNames"],
      "additionalProperties": false,
      "description": "Program-level configuration: the points names kept from before points were switched off."
    },
    "sectionsEnabled": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "boolean",
          "description": "Whether the ways-to-earn section is shown to members."
        },
        "offers": {
          "type": "boolean",
          "description": "Whether the offers section is shown to members."
        }
      },
      "required": ["rules", "offers"],
      "additionalProperties": false,
      "description": "Which optional sections members see in the loyalty widget."
    },
    "pointsNames": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "singular": {
              "type": "string",
              "minLength": 1,
              "description": "The name of one point, such as `point`."
            },
            "plural": {
              "type": "string",
              "minLength": 1,
              "description": "The name of several points, such as `points`."
            }
          },
          "required": ["singular", "plural"],
          "additionalProperties": false,
          "description": "Unit names a balance is composed from, for example `12 points`."
        },
        {
          "type": "null"
        }
      ],
      "description": "What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them."
    },
    "pointsExpiresAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Each earn expires this many days after it happened. Null means earns never age out. When `pointsBalancesExpireAt` is also set, the earlier of the two applies."
    },
    "pointsBalancesExpireAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When `pointsExpiresAfterDays` is also set, the earlier of the two applies."
    },
    "rewardsExpireAfterDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this."
    },
    "expiringSoonDays": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out."
    },
    "pausedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was paused. While it is set the program earns nothing, and members keep their balances, rewards and history."
    },
    "publishedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the program was published. Null means it is still a draft: no shopper can see it, join it or earn in it, and only a preview link reaches it. Publishing cannot be undone, so pause a program you want to take down."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "autoMembership",
    "settings",
    "sectionsEnabled",
    "pointsNames",
    "pointsExpiresAfterDays",
    "pointsBalancesExpireAt",
    "rewardsExpireAfterDays",
    "expiringSoonDays",
    "pausedAt",
    "publishedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The deleted program."
}

POST `/loyalty-programs/{id}/publish`

Publish a draft loyalty program, which is what makes it visible to shoppers. A new program starts as a draft: nothing enrolls, earns or shows up in the storefront widget until this is called. Publishing cannot be undone, so pause the program if you want to take it down later. Publishing a program with no rules, or one no site shows, is allowed and comes back with a warning saying it will not do anything visible yet. Calling it on a program that is already published changes nothing. Triggers the loyaltyProgram.updated webhook.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program to publish.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz/publish" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { postLoyaltyProgramsByIdPublish } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postLoyaltyProgramsByIdPublish({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.publish("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.publish("A4Ws1igz")

Response

{
  "data": {
    "id": "A4Ws1igz",
    "name": "string",
    "autoMembership": "off",
    "settings": {
      "previousPointsNames": null
    },
    "sectionsEnabled": {
      "rules": true,
      "offers": true
    },
    "pointsNames": {
      "singular": "string",
      "plural": "string"
    },
    "pointsExpiresAfterDays": 0,
    "pointsBalancesExpireAt": "2025-01-15T09:30:00Z",
    "rewardsExpireAfterDays": 0,
    "expiringSoonDays": 0,
    "pausedAt": "2025-01-15T09:30:00Z",
    "publishedAt": "2025-01-15T09:30:00Z",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "warnings": [
    {
      "code": "noRules",
      "message": "string"
    }
  ]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the loyalty program.",
          "idCodec": "sqid"
        },
        "name": {
          "type": "string",
          "description": "The program's display name, shown to members."
        },
        "autoMembership": {
          "type": "string",
          "enum": ["off", "onFirstActivity"],
          "description": "When customers are enrolled in the program automatically. `off` means they join only when enrolled explicitly; `onFirstActivity` enrolls them the first time they do something the program rewards."
        },
        "settings": {
          "type": "object",
          "properties": {
            "previousPointsNames": {
              "default": null,
              "description": "The names the points had before they were switched off, kept so switching them back on restores them. Null when points have never been switched off.",
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "singular": {
                      "type": "string",
                      "minLength": 1,
                      "description": "The name of one point, such as `point`."
                    },
                    "plural": {
                      "type": "string",
                      "minLength": 1,
                      "description": "The name of several points, such as `points`."
                    }
                  },
                  "required": ["singular", "plural"],
                  "additionalProperties": false,
                  "description": "Unit names a balance is composed from, for example `12 points`."
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": ["previousPointsNames"],
          "additionalProperties": false,
          "description": "Program-level configuration: the points names kept from before points were switched off."
        },
        "sectionsEnabled": {
          "type": "object",
          "properties": {
            "rules": {
              "type": "boolean",
              "description": "Whether the ways-to-earn section is shown to members."
            },
            "offers": {
              "type": "boolean",
              "description": "Whether the offers section is shown to members."
            }
          },
          "required": ["rules", "offers"],
          "additionalProperties": false,
          "description": "Which optional sections members see in the loyalty widget."
        },
        "pointsNames": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "singular": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of one point, such as `point`."
                },
                "plural": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The name of several points, such as `points`."
                }
              },
              "required": ["singular", "plural"],
              "additionalProperties": false,
              "description": "Unit names a balance is composed from, for example `12 points`."
            },
            {
              "type": "null"
            }
          ],
          "description": "What the program calls its points, singular and plural. Null means the program has no points, so nothing earns, spends or displays them."
        },
        "pointsExpiresAfterDays": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "Each earn expires this many days after it happened. Null means earns never age out. When `pointsBalancesExpireAt` is also set, the earlier of the two applies."
        },
        "pointsBalancesExpireAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "Every points balance in the program expires at this moment, the event-tickets case. Null means balances have no fixed end date. When `pointsExpiresAfterDays` is also set, the earlier of the two applies."
        },
        "rewardsExpireAfterDays": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "Rewards issued in this program lapse this many days after a member gets them. Null means they stay redeemable until they are used. A rule that sets its own expiry wins over this."
        },
        "expiringSoonDays": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "How many days of warning members get before a reward or a points balance lapses. Null means no warning goes out."
        },
        "pausedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the program was paused. While it is set the program earns nothing, and members keep their balances, rewards and history."
        },
        "publishedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the program was published. Null means it is still a draft: no shopper can see it, join it or earn in it, and only a preview link reaches it. Publishing cannot be undone, so pause a program you want to take down."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the program was created."
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the program was last changed."
        }
      },
      "required": [
        "id",
        "name",
        "autoMembership",
        "settings",
        "sectionsEnabled",
        "pointsNames",
        "pointsExpiresAfterDays",
        "pointsBalancesExpireAt",
        "rewardsExpireAfterDays",
        "expiringSoonDays",
        "pausedAt",
        "publishedAt",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false,
      "description": "The published program."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": ["noRules", "noSites"],
            "description": "What is missing: `noRules` for a program with nothing to earn, `noSites` for one no storefront shows."
          },
          "message": {
            "type": "string",
            "description": "The warning in a sentence, ready to show a merchant."
          }
        },
        "required": ["code", "message"],
        "additionalProperties": false
      },
      "description": "Reasons the program will not do anything visible yet. None of them block it."
    }
  },
  "required": ["data", "warnings"],
  "additionalProperties": false
}

POST `/loyalty-programs/{id}/preview`

Mint a preview link for a loyalty program, which is how a draft is checked before it is published. The link opens the site's loyalty page carrying a short-lived signed token, and the storefront widget shows the program to whoever follows it, published or not. Anyone holding the link can read the program, so it is only ever as private as where you paste it. The preview is read only: nobody can join or claim through it. A program attached to no site still gets a token, but there is nowhere to open it.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program to preview.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz/preview" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { postLoyaltyProgramsByIdPreview } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postLoyaltyProgramsByIdPreview({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.preview("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.preview("A4Ws1igz")

Response

{
  "token": "string",
  "expiresAt": "2025-01-15T09:30:00Z",
  "sites": [
    {
      "siteId": "A4Ws1igz",
      "siteName": "string",
      "siteSlug": "string",
      "url": "string"
    }
  ]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The signed preview token. Anyone holding it can read this one program through the widget API, published or not, until it expires."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the token stops working."
    },
    "sites": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "siteId": {
            "type": "string",
            "description": "The site the link opens.",
            "idCodec": "sqid"
          },
          "siteName": {
            "type": "string",
            "description": "The site's display name."
          },
          "siteSlug": {
            "type": "string",
            "description": "The site's slug."
          },
          "url": {
            "type": "string",
            "description": "The site's loyalty page carrying the preview token and the `#meisei-rewards` fragment."
          }
        },
        "required": ["siteId", "siteName", "siteSlug", "url"],
        "additionalProperties": false
      },
      "description": "One link per site the program is attached to. Empty when no site shows the program, in which case there is nowhere to open the preview."
    }
  },
  "required": ["token", "expiresAt", "sites"],
  "additionalProperties": false,
  "description": "The token and where to open it."
}

GET `/loyalty-programs/{id}/sites`

List the sites a loyalty program is attached to, along with the page on each one that shows it. A program is attached to every site when it is created, and a new site is attached to every program, so this is normally the organization's whole site list. The storefront widget resolves a shopper's program through it, and a site with nothing attached falls back to every program in the organization.

Requires the loyalty:read permission.

Path parameters

idstringrequired

The ID of the loyalty program.

Request

curl \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz/sites" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getLoyaltyProgramsByIdSites } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getLoyaltyProgramsByIdSites({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

page = meisei.loyalty_programs.sites.list("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

page = meisei.loyalty_programs.sites.list("A4Ws1igz")

Response

{
  "data": [
    {
      "id": "A4Ws1igz",
      "siteId": "A4Ws1igz",
      "siteName": "string",
      "siteSlug": "string",
      "loyaltyProgramId": "A4Ws1igz",
      "programUrl": "string",
      "createdAt": "2025-01-15T09:30:00Z"
    }
  ]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the link between the site and the program.",
            "idCodec": "sqid"
          },
          "siteId": {
            "type": "string",
            "description": "The site the program is attached to.",
            "idCodec": "sqid"
          },
          "siteName": {
            "type": "string",
            "description": "The site's display name."
          },
          "siteSlug": {
            "type": "string",
            "description": "The site's slug, which the widget identifies it by."
          },
          "loyaltyProgramId": {
            "type": "string",
            "description": "The loyalty program the site is attached to.",
            "idCodec": "sqid"
          },
          "programUrl": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The page on the site that shows the loyalty program, used by the links in the member emails. Null means the site's base URL, where the launcher embed is expected to be."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the program was attached to the site."
          }
        },
        "required": [
          "id",
          "siteId",
          "siteName",
          "siteSlug",
          "loyaltyProgramId",
          "programUrl",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "description": "The sites, alphabetically."
    }
  },
  "required": ["data"],
  "additionalProperties": false
}

POST `/loyalty-programs/{id}/sites`

Attach a loyalty program to one of the organization's sites. Every program is attached to every site by default, so this only does something for a site that was detached through the API. Attaching the same program twice fails with a conflict.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program.

Body parameters

siteIdstringrequired

The ID of the site to attach the program to.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz/sites" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "siteId": "string"
}'

Request

import { client } from "@meisei/api/admin/client"
import { postLoyaltyProgramsByIdSites } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postLoyaltyProgramsByIdSites({
  path: { id: "A4Ws1igz" },
  body: {
    siteId: "string",
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.sites.create("A4Ws1igz", site_id: "string")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.sites.create("A4Ws1igz", site_id="string")

Response

{
  "id": "A4Ws1igz",
  "siteId": "A4Ws1igz",
  "siteName": "string",
  "siteSlug": "string",
  "loyaltyProgramId": "A4Ws1igz",
  "programUrl": "string",
  "createdAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the link between the site and the program.",
      "idCodec": "sqid"
    },
    "siteId": {
      "type": "string",
      "description": "The site the program is attached to.",
      "idCodec": "sqid"
    },
    "siteName": {
      "type": "string",
      "description": "The site's display name."
    },
    "siteSlug": {
      "type": "string",
      "description": "The site's slug, which the widget identifies it by."
    },
    "loyaltyProgramId": {
      "type": "string",
      "description": "The loyalty program the site is attached to.",
      "idCodec": "sqid"
    },
    "programUrl": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The page on the site that shows the loyalty program, used by the links in the member emails. Null means the site's base URL, where the launcher embed is expected to be."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was attached to the site."
    }
  },
  "required": [
    "id",
    "siteId",
    "siteName",
    "siteSlug",
    "loyaltyProgramId",
    "programUrl",
    "createdAt"
  ],
  "additionalProperties": false,
  "description": "The new link."
}

PATCH `/loyalty-programs/{id}/sites/{siteId}`

Set the page on a site that shows the loyalty program. The links in the member emails point at it. Leave it empty and they point at the site's base URL instead, which is where the launcher embed usually sits.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program.

siteIdstringrequired

The ID of the site the program is attached to.

Body parameters

programUrlstring (uri) | nullrequired

The page that shows the program, such as https://shop.example.com/pages/rewards. Null clears it.

Request

curl \
  -X PATCH \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz/sites/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "programUrl": "https://example.com"
}'

Request

import { client } from "@meisei/api/admin/client"
import { patchLoyaltyProgramsByIdSitesBySiteId } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await patchLoyaltyProgramsByIdSitesBySiteId({
  path: { id: "A4Ws1igz", siteId: "A4Ws1igz" },
  body: {
    programUrl: "https://example.com",
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.sites.update(
  "A4Ws1igz",
  "A4Ws1igz",
  program_url: "https://example.com",
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.sites.update(
    "A4Ws1igz",
    "A4Ws1igz",
    program_url="https://example.com",
)

Response

{
  "id": "A4Ws1igz",
  "siteId": "A4Ws1igz",
  "siteName": "string",
  "siteSlug": "string",
  "loyaltyProgramId": "A4Ws1igz",
  "programUrl": "string",
  "createdAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the link between the site and the program.",
      "idCodec": "sqid"
    },
    "siteId": {
      "type": "string",
      "description": "The site the program is attached to.",
      "idCodec": "sqid"
    },
    "siteName": {
      "type": "string",
      "description": "The site's display name."
    },
    "siteSlug": {
      "type": "string",
      "description": "The site's slug, which the widget identifies it by."
    },
    "loyaltyProgramId": {
      "type": "string",
      "description": "The loyalty program the site is attached to.",
      "idCodec": "sqid"
    },
    "programUrl": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The page on the site that shows the loyalty program, used by the links in the member emails. Null means the site's base URL, where the launcher embed is expected to be."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was attached to the site."
    }
  },
  "required": [
    "id",
    "siteId",
    "siteName",
    "siteSlug",
    "loyaltyProgramId",
    "programUrl",
    "createdAt"
  ],
  "additionalProperties": false,
  "description": "The updated link."
}

DELETE `/loyalty-programs/{id}/sites/{siteId}`

Detach a loyalty program from a site. Nothing moves: memberships, balances and rewards belong to the program rather than the site, so the site simply stops showing it. The loyalty page URL set on the link goes with it. The admin has no control for this: programs apply to every site unless you detach one here.

Requires the loyalty:write permission.

Path parameters

idstringrequired

The ID of the loyalty program.

siteIdstringrequired

The ID of the site to detach it from.

Request

curl \
  -X DELETE \
  "https://your-store.meisei.app/api/loyalty-programs/A4Ws1igz/sites/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { deleteLoyaltyProgramsByIdSitesBySiteId } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteLoyaltyProgramsByIdSitesBySiteId({
  path: { id: "A4Ws1igz", siteId: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.sites.delete("A4Ws1igz", "A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.loyalty_programs.sites.delete("A4Ws1igz", "A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "siteId": "A4Ws1igz",
  "siteName": "string",
  "siteSlug": "string",
  "loyaltyProgramId": "A4Ws1igz",
  "programUrl": "string",
  "createdAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the link between the site and the program.",
      "idCodec": "sqid"
    },
    "siteId": {
      "type": "string",
      "description": "The site the program is attached to.",
      "idCodec": "sqid"
    },
    "siteName": {
      "type": "string",
      "description": "The site's display name."
    },
    "siteSlug": {
      "type": "string",
      "description": "The site's slug, which the widget identifies it by."
    },
    "loyaltyProgramId": {
      "type": "string",
      "description": "The loyalty program the site is attached to.",
      "idCodec": "sqid"
    },
    "programUrl": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The page on the site that shows the loyalty program, used by the links in the member emails. Null means the site's base URL, where the launcher embed is expected to be."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the program was attached to the site."
    }
  },
  "required": [
    "id",
    "siteId",
    "siteName",
    "siteSlug",
    "loyaltyProgramId",
    "programUrl",
    "createdAt"
  ],
  "additionalProperties": false,
  "description": "The removed link."
}

#Loyalty programs

GET /loyalty-programs

Query parameters

POST /loyalty-programs

Body parameters

GET /loyalty-programs/{id}

Path parameters

Query parameters

PUT /loyalty-programs/{id}

Path parameters

Body parameters

DELETE /loyalty-programs/{id}

Path parameters

Body parameters

POST /loyalty-programs/{id}/publish

Path parameters

POST /loyalty-programs/{id}/preview

Path parameters

GET /loyalty-programs/{id}/sites

Path parameters

POST /loyalty-programs/{id}/sites

Path parameters

Body parameters

PATCH /loyalty-programs/{id}/sites/{siteId}

Path parameters

Body parameters

DELETE /loyalty-programs/{id}/sites/{siteId}

Path parameters

Loyalty programs

GET `/loyalty-programs`

POST `/loyalty-programs`

GET `/loyalty-programs/{id}`

PUT `/loyalty-programs/{id}`

DELETE `/loyalty-programs/{id}`

POST `/loyalty-programs/{id}/publish`

POST `/loyalty-programs/{id}/preview`

GET `/loyalty-programs/{id}/sites`

POST `/loyalty-programs/{id}/sites`

PATCH `/loyalty-programs/{id}/sites/{siteId}`

DELETE `/loyalty-programs/{id}/sites/{siteId}`