Loyalty tiers

GET `/loyalty-tiers`

List the tiers defined across the organization's loyalty programs, alphabetically by default. Archived tiers are included.

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.

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

filterstring

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

Request

curl \
  "https://api.cascade.dev/loyalty-tiers" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { getLoyaltyTiers } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getLoyaltyTiers()

Request

require "net/http"

uri = URI("https://api.cascade.dev/loyalty-tiers")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/loyalty-tiers",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
      "threshold": {
        "type": "...",
        "amount": "...",
        "window": "..."
      },
      "pointsMultiplier": 0,
      "color": "string",
      "metadata": "...",
      "archivedAt": "2025-01-15T09:30:00Z",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "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",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the tier."
          },
          "name": {
            "type": "string",
            "description": "The tier's display name, shown to members."
          },
          "loyaltyProgramId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The loyalty program the tier belongs to."
          },
          "threshold": {
            "anyOf": [
              {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "const": "earnedPoints",
                        "description": "The tier is attained by earning points."
                      },
                      "amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "How many points have to be earned within the window to attain the tier."
                      },
                      "window": {
                        "type": "string",
                        "enum": ["lifetime", "rolling12Months"],
                        "description": "The period earning is summed over. `lifetime` counts everything the member ever earned; `rolling12Months` counts the last 12 months."
                      }
                    },
                    "required": ["type", "amount", "window"],
                    "additionalProperties": false
                  }
                ],
                "description": "What a member has to do to attain the tier."
              },
              {
                "type": "null"
              }
            ],
            "description": "What a member has to earn to attain the tier, or null for a tier that is only assigned by hand. Members are promoted as soon as they qualify; a member who stops qualifying for a rolling-window tier is only moved down when their current 12-month review date passes."
          },
          "pointsMultiplier": {
            "type": "number",
            "description": "Multiplies points issued by rules for members of this tier, for example 2 for double points. It never applies to manual adjustments, imports, or non-points rewards."
          },
          "color": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "A CSS color used to badge the tier, or null for the default look."
          },
          "metadata": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
          },
          "archivedAt": {
            "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 tier was archived, or null if it is still in use. Archived tiers take no new members but keep the ones they have."
          },
          "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 tier 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 tier was last changed."
          }
        },
        "required": [
          "id",
          "name",
          "loyaltyProgramId",
          "threshold",
          "pointsMultiplier",
          "color",
          "metadata",
          "archivedAt",
          "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-tiers`

Create a loyalty tier inside a program. Triggers the loyaltyTier.created webhook.

Requires the loyalty:write permission.

Body Parameters

dataobjectrequired

The tier to create.

Request

curl \
  -X POST \
  "https://api.cascade.dev/loyalty-tiers" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": "string",
    "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
    "threshold": {
      "type": "earnedPoints",
      "amount": 0,
      "window": "lifetime"
    },
    "pointsMultiplier": 0,
    "color": "string",
    "metadata": "..."
  }
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { postLoyaltyTiers } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postLoyaltyTiers({
  body: {
    data: {
      name: "string",
      loyaltyProgramId: "550e8400-e29b-41d4-a716-446655440000",
      threshold: {
        type: "earnedPoints",
        amount: 0,
        window: "lifetime",
      },
      pointsMultiplier: 0,
      color: "string",
      metadata: "...",
    },
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/loyalty-tiers")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "data": {
      "name": "string",
      "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
      "threshold": {
        "type": "earnedPoints",
        "amount": 0,
        "window": "lifetime"
      },
      "pointsMultiplier": 0,
      "color": "string",
      "metadata": "..."
    }
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "data": {
    "name": "string",
    "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
    "threshold": {
      "type": "earnedPoints",
      "amount": 0,
      "window": "lifetime"
    },
    "pointsMultiplier": 0,
    "color": "string",
    "metadata": "..."
  }
}"""

req = Request(
    "https://api.cascade.dev/loyalty-tiers",
    data=body.encode(),
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "threshold": {
    "type": "earnedPoints",
    "amount": 0,
    "window": "lifetime"
  },
  "pointsMultiplier": 0,
  "color": "string",
  "metadata": "...",
  "archivedAt": "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",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the tier."
    },
    "name": {
      "type": "string",
      "description": "The tier's display name, shown to members."
    },
    "loyaltyProgramId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The loyalty program the tier belongs to."
    },
    "threshold": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "earnedPoints",
                  "description": "The tier is attained by earning points."
                },
                "amount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "description": "How many points have to be earned within the window to attain the tier."
                },
                "window": {
                  "type": "string",
                  "enum": ["lifetime", "rolling12Months"],
                  "description": "The period earning is summed over. `lifetime` counts everything the member ever earned; `rolling12Months` counts the last 12 months."
                }
              },
              "required": ["type", "amount", "window"],
              "additionalProperties": false
            }
          ],
          "description": "What a member has to do to attain the tier."
        },
        {
          "type": "null"
        }
      ],
      "description": "What a member has to earn to attain the tier, or null for a tier that is only assigned by hand. Members are promoted as soon as they qualify; a member who stops qualifying for a rolling-window tier is only moved down when their current 12-month review date passes."
    },
    "pointsMultiplier": {
      "type": "number",
      "description": "Multiplies points issued by rules for members of this tier, for example 2 for double points. It never applies to manual adjustments, imports, or non-points rewards."
    },
    "color": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "A CSS color used to badge the tier, or null for the default look."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "archivedAt": {
      "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 tier was archived, or null if it is still in use. Archived tiers take no new members but keep the ones they have."
    },
    "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 tier 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 tier was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "loyaltyProgramId",
    "threshold",
    "pointsMultiplier",
    "color",
    "metadata",
    "archivedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The new loyalty tier."
}

GET `/loyalty-tiers/{id}`

Get a single loyalty tier by ID.

Requires the loyalty:read permission.

Path Parameters

idstring (uuid)required

The ID of the loyalty tier.

Request

curl \
  "https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { getLoyaltyTiersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getLoyaltyTiersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "threshold": {
    "type": "earnedPoints",
    "amount": 0,
    "window": "lifetime"
  },
  "pointsMultiplier": 0,
  "color": "string",
  "metadata": "...",
  "archivedAt": "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",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the tier."
    },
    "name": {
      "type": "string",
      "description": "The tier's display name, shown to members."
    },
    "loyaltyProgramId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The loyalty program the tier belongs to."
    },
    "threshold": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "earnedPoints",
                  "description": "The tier is attained by earning points."
                },
                "amount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "description": "How many points have to be earned within the window to attain the tier."
                },
                "window": {
                  "type": "string",
                  "enum": ["lifetime", "rolling12Months"],
                  "description": "The period earning is summed over. `lifetime` counts everything the member ever earned; `rolling12Months` counts the last 12 months."
                }
              },
              "required": ["type", "amount", "window"],
              "additionalProperties": false
            }
          ],
          "description": "What a member has to do to attain the tier."
        },
        {
          "type": "null"
        }
      ],
      "description": "What a member has to earn to attain the tier, or null for a tier that is only assigned by hand. Members are promoted as soon as they qualify; a member who stops qualifying for a rolling-window tier is only moved down when their current 12-month review date passes."
    },
    "pointsMultiplier": {
      "type": "number",
      "description": "Multiplies points issued by rules for members of this tier, for example 2 for double points. It never applies to manual adjustments, imports, or non-points rewards."
    },
    "color": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "A CSS color used to badge the tier, or null for the default look."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "archivedAt": {
      "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 tier was archived, or null if it is still in use. Archived tiers take no new members but keep the ones they have."
    },
    "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 tier 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 tier was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "loyaltyProgramId",
    "threshold",
    "pointsMultiplier",
    "color",
    "metadata",
    "archivedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The requested loyalty tier."
}

PUT `/loyalty-tiers/{id}`

Rename a loyalty tier, change its metadata, or archive it so it takes no new members. Triggers the loyaltyTier.updated webhook.

Requires the loyalty:write permission.

Path Parameters

idstring (uuid)required

The ID of the loyalty tier to update.

Body Parameters

dataobjectrequired

The fields to update.

Request

curl \
  -X PUT \
  "https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": "string",
    "threshold": {
      "type": "earnedPoints",
      "amount": 0,
      "window": "lifetime"
    },
    "pointsMultiplier": 0,
    "color": "string",
    "metadata": "...",
    "archived": true
  }
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { putLoyaltyTiersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await putLoyaltyTiersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
  body: {
    data: {
      name: "string",
      threshold: {
        type: "earnedPoints",
        amount: 0,
        window: "lifetime",
      },
      pointsMultiplier: 0,
      color: "string",
      metadata: "...",
      archived: true,
    },
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Put.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "data": {
      "name": "string",
      "threshold": {
        "type": "earnedPoints",
        "amount": 0,
        "window": "lifetime"
      },
      "pointsMultiplier": 0,
      "color": "string",
      "metadata": "...",
      "archived": true
    }
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "data": {
    "name": "string",
    "threshold": {
      "type": "earnedPoints",
      "amount": 0,
      "window": "lifetime"
    },
    "pointsMultiplier": 0,
    "color": "string",
    "metadata": "...",
    "archived": true
  }
}"""

req = Request(
    "https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000",
    data=body.encode(),
    method="PUT",
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "threshold": {
    "type": "earnedPoints",
    "amount": 0,
    "window": "lifetime"
  },
  "pointsMultiplier": 0,
  "color": "string",
  "metadata": "...",
  "archivedAt": "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",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the tier."
    },
    "name": {
      "type": "string",
      "description": "The tier's display name, shown to members."
    },
    "loyaltyProgramId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The loyalty program the tier belongs to."
    },
    "threshold": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "earnedPoints",
                  "description": "The tier is attained by earning points."
                },
                "amount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "description": "How many points have to be earned within the window to attain the tier."
                },
                "window": {
                  "type": "string",
                  "enum": ["lifetime", "rolling12Months"],
                  "description": "The period earning is summed over. `lifetime` counts everything the member ever earned; `rolling12Months` counts the last 12 months."
                }
              },
              "required": ["type", "amount", "window"],
              "additionalProperties": false
            }
          ],
          "description": "What a member has to do to attain the tier."
        },
        {
          "type": "null"
        }
      ],
      "description": "What a member has to earn to attain the tier, or null for a tier that is only assigned by hand. Members are promoted as soon as they qualify; a member who stops qualifying for a rolling-window tier is only moved down when their current 12-month review date passes."
    },
    "pointsMultiplier": {
      "type": "number",
      "description": "Multiplies points issued by rules for members of this tier, for example 2 for double points. It never applies to manual adjustments, imports, or non-points rewards."
    },
    "color": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "A CSS color used to badge the tier, or null for the default look."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "archivedAt": {
      "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 tier was archived, or null if it is still in use. Archived tiers take no new members but keep the ones they have."
    },
    "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 tier 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 tier was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "loyaltyProgramId",
    "threshold",
    "pointsMultiplier",
    "color",
    "metadata",
    "archivedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The updated loyalty tier."
}

DELETE `/loyalty-tiers/{id}`

Delete a loyalty tier. Archive it instead if members are still assigned to it. Triggers the loyaltyTier.deleted webhook.

Requires the loyalty:write permission.

Path Parameters

idstring (uuid)required

The ID of the loyalty tier to delete.

Request

curl \
  -X DELETE \
  "https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { deleteLoyaltyTiersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteLoyaltyTiersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Delete.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/loyalty-tiers/550e8400-e29b-41d4-a716-446655440000",
    method="DELETE",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "threshold": {
    "type": "earnedPoints",
    "amount": 0,
    "window": "lifetime"
  },
  "pointsMultiplier": 0,
  "color": "string",
  "metadata": "...",
  "archivedAt": "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",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the tier."
    },
    "name": {
      "type": "string",
      "description": "The tier's display name, shown to members."
    },
    "loyaltyProgramId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The loyalty program the tier belongs to."
    },
    "threshold": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "earnedPoints",
                  "description": "The tier is attained by earning points."
                },
                "amount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "description": "How many points have to be earned within the window to attain the tier."
                },
                "window": {
                  "type": "string",
                  "enum": ["lifetime", "rolling12Months"],
                  "description": "The period earning is summed over. `lifetime` counts everything the member ever earned; `rolling12Months` counts the last 12 months."
                }
              },
              "required": ["type", "amount", "window"],
              "additionalProperties": false
            }
          ],
          "description": "What a member has to do to attain the tier."
        },
        {
          "type": "null"
        }
      ],
      "description": "What a member has to earn to attain the tier, or null for a tier that is only assigned by hand. Members are promoted as soon as they qualify; a member who stops qualifying for a rolling-window tier is only moved down when their current 12-month review date passes."
    },
    "pointsMultiplier": {
      "type": "number",
      "description": "Multiplies points issued by rules for members of this tier, for example 2 for double points. It never applies to manual adjustments, imports, or non-points rewards."
    },
    "color": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "A CSS color used to badge the tier, or null for the default look."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "archivedAt": {
      "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 tier was archived, or null if it is still in use. Archived tiers take no new members but keep the ones they have."
    },
    "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 tier 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 tier was last changed."
    }
  },
  "required": [
    "id",
    "name",
    "loyaltyProgramId",
    "threshold",
    "pointsMultiplier",
    "color",
    "metadata",
    "archivedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The deleted loyalty tier."
}

#Loyalty tiers

GET /loyalty-tiers

Query Parameters

POST /loyalty-tiers

Body Parameters

GET /loyalty-tiers/{id}

Path Parameters

PUT /loyalty-tiers/{id}

Path Parameters

Body Parameters

DELETE /loyalty-tiers/{id}

Path Parameters

Loyalty tiers

GET `/loyalty-tiers`

POST `/loyalty-tiers`

GET `/loyalty-tiers/{id}`

PUT `/loyalty-tiers/{id}`

DELETE `/loyalty-tiers/{id}`