Cascade

    Loyalty rules

    GET /loyalty-rules

    List the earning rules across the organization's loyalty programs, oldest first by default. Each rule pairs a trigger with the reward it grants. Pass include=stats for what each rule has issued and how much of that has been redeemed. Supports search, filtering and cursor pagination.

    Requires the loyalty:read permission.

    Query Parameters

    limitnumber

    The number of records to return.

    cursorstring

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

    sortname | -name | createdAt | -createdAt | rewardType | -rewardType

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

    searchstring

    A free-text search term, matched case-insensitively against the record's most identifying fields. Combined with filter using AND.

    filterstring

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

    includestring

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

    availableAtstring (date-time)

    Return only rules that are live at this moment in time.

    Request
    curl \
  "https://api.cascade.dev/loyalty-rules" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
      "section": "rules",
      "name": "string",
      "trigger": {
        "type": "...",
        "source": "..."
      },
      "reward": {
        "type": "...",
        "amount": "..."
      },
      "maxRedemptionsPerCustomer": 0,
      "maxAvailableCount": 0,
      "availableCount": 0,
      "availableFrom": "2025-01-15T09:30:00Z",
      "availableTo": "2025-01-15T09:30:00Z",
      "loyaltyTierIds": ["..."],
      "metadata": "...",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "stats": {
        "issuedCount": "...",
        "redeemedCount": "..."
      }
    }
  ],
  "nextCursor": "string"
}

    POST /loyalty-rules

    Create an earning rule: a trigger paired with the reward it grants. A points reward needs the program to have points named, a stampsEarned trigger needs one of the program's stamp card types, and any product filter has to name products and tags that exist.

    Requires the loyalty:write permission.

    Body Parameters

    dataobjectrequired

    The rule to create.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/loyalty-rules" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
    "section": "rules",
    "name": "string",
    "trigger": {
      "type": "joinProgram",
      "source": "direct"
    },
    "reward": {
      "type": "points",
      "amount": 0
    },
    "maxRedemptionsPerCustomer": 0,
    "maxAvailableCount": 0,
    "availableFrom": "2025-01-15T09:30:00Z",
    "availableTo": "2025-01-15T09:30:00Z",
    "loyaltyTierIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "metadata": "..."
  }
}'
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "section": "rules",
  "name": "string",
  "trigger": {
    "type": "joinProgram",
    "source": "direct"
  },
  "reward": {
    "type": "points",
    "amount": 0
  },
  "maxRedemptionsPerCustomer": 0,
  "maxAvailableCount": 0,
  "availableCount": 0,
  "availableFrom": "2025-01-15T09:30:00Z",
  "availableTo": "2025-01-15T09:30:00Z",
  "loyaltyTierIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

    POST /loyalty-rules/{id}/webhook-token

    Generate a new token for a rule triggered by an event, which stops every caller still sending the old one. The rotation is recorded in the audit trail. Triggers the loyaltyRule.updated webhook.

    Requires the loyalty:write permission.

    Path Parameters

    idstring (uuid)required

    The ID of the loyalty rule.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/loyalty-rules/550e8400-e29b-41d4-a716-446655440000/webhook-token" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "section": "rules",
  "name": "string",
  "trigger": {
    "type": "joinProgram",
    "source": "direct"
  },
  "reward": {
    "type": "points",
    "amount": 0
  },
  "maxRedemptionsPerCustomer": 0,
  "maxAvailableCount": 0,
  "availableCount": 0,
  "availableFrom": "2025-01-15T09:30:00Z",
  "availableTo": "2025-01-15T09:30:00Z",
  "loyaltyTierIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

    GET /loyalty-rules/{id}

    Get a single loyalty rule by ID.

    Requires the loyalty:read permission.

    Path Parameters

    idstring (uuid)required

    The ID of the loyalty rule.

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

    Request
    curl \
  "https://api.cascade.dev/loyalty-rules/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "section": "rules",
  "name": "string",
  "trigger": {
    "type": "joinProgram",
    "source": "direct"
  },
  "reward": {
    "type": "points",
    "amount": 0
  },
  "maxRedemptionsPerCustomer": 0,
  "maxAvailableCount": 0,
  "availableCount": 0,
  "availableFrom": "2025-01-15T09:30:00Z",
  "availableTo": "2025-01-15T09:30:00Z",
  "loyaltyTierIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "stats": {
    "issuedCount": 0,
    "redeemedCount": 0
  }
}

    PUT /loyalty-rules/{id}

    Update a loyalty rule. The loyalty program it belongs to cannot change. Rewards already issued keep the configuration they were issued under, and the change is recorded in the audit trail.

    Requires the loyalty:write permission.

    Path Parameters

    idstring (uuid)required

    The ID of the loyalty rule to update.

    Body Parameters

    dataobjectrequired

    The fields to update.

    Request
    curl \
  -X PUT \
  "https://api.cascade.dev/loyalty-rules/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "section": "rules",
    "name": "string",
    "trigger": {
      "type": "joinProgram",
      "source": "direct"
    },
    "reward": {
      "type": "points",
      "amount": 0
    },
    "maxRedemptionsPerCustomer": 0,
    "maxAvailableCount": 0,
    "availableFrom": "2025-01-15T09:30:00Z",
    "availableTo": "2025-01-15T09:30:00Z",
    "loyaltyTierIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "metadata": "..."
  }
}'
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "section": "rules",
  "name": "string",
  "trigger": {
    "type": "joinProgram",
    "source": "direct"
  },
  "reward": {
    "type": "points",
    "amount": 0
  },
  "maxRedemptionsPerCustomer": 0,
  "maxAvailableCount": 0,
  "availableCount": 0,
  "availableFrom": "2025-01-15T09:30:00Z",
  "availableTo": "2025-01-15T09:30:00Z",
  "loyaltyTierIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

    DELETE /loyalty-rules/{id}

    Delete a loyalty rule. Rewards and activity it already produced are kept, so deleting it only stops future awards.

    Requires the loyalty:write permission.

    Path Parameters

    idstring (uuid)required

    The ID of the loyalty rule to delete.

    Request
    curl \
  -X DELETE \
  "https://api.cascade.dev/loyalty-rules/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
  "section": "rules",
  "name": "string",
  "trigger": {
    "type": "joinProgram",
    "source": "direct"
  },
  "reward": {
    "type": "points",
    "amount": 0
  },
  "maxRedemptionsPerCustomer": 0,
  "maxAvailableCount": 0,
  "availableCount": 0,
  "availableFrom": "2025-01-15T09:30:00Z",
  "availableTo": "2025-01-15T09:30:00Z",
  "loyaltyTierIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}