Cascade

    Wishlists

    These endpoints are called from a shopper's browser, so they take your publishable key rather than a secret one. Anything specific to one customer also takes a signed email and timestamp: see Identifying the customer for how to produce the signature.

    GET /widgets/wishlists/for-product

    List the current customer's wishlists plus whether each contains a product. The customer parameters are optional here: with the publishable key alone it returns the store's wishlist settings and an empty list, which is how the widget renders for a shopper who is not signed in

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)

    The signed-in shopper's address. Leave it out for a shopper who is not signed in.

    timestampstring

    The Unix seconds the signature was made at. Required with customerEmail.

    signaturestring

    The HMAC of the email and timestamp. Required with customerEmail.

    productSlugstringrequired

    Slug of the product. On Shopify this is the product handle.

    Request
    curl \
  "https://api.cascade.dev/widgets/wishlists/for-product?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&productSlug=string"
    Response
    {
  "productSlug": "string",
  "productFound": true,
  "wishlists": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "itemsCount": 0,
      "shared": true,
      "shareUrl": "https://example.com",
      "isDefault": true,
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "hasProduct": true,
      "productItemId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "sharingEnabled": true,
  "multipleWishlists": true
}

    POST /widgets/wishlists/claim

    Move the lists a shopper saved in their browser before signing in onto their customer record. When the store allows several lists, each browser list becomes a new wishlist and a name that is already taken gets a numbered suffix. When it keeps one list per customer, everything flattens into the default list. An item already on the target list is left exactly as it is. The whole claim succeeds or fails together, so the browser can keep its copy until the response confirms the merge

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    listsobject[]required

    The lists the shopper built in their browser before signing in.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/widgets/wishlists/claim?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "lists": [
    {
      "name": "string",
      "items": [
        "..."
      ]
    }
  ]
}'
    Response
    {
  "wishlists": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "itemsCount": 0,
      "shared": true,
      "shareUrl": "https://example.com",
      "isDefault": true,
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "sharingEnabled": true,
  "multipleWishlists": true,
  "claimedLists": 0,
  "claimedItems": 0,
  "skippedItems": 0
}

    POST /widgets/wishlists/default/toggle-item

    Toggle a product on the customer's default wishlist, creating the default list on first use

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    productSlugstringrequired

    Slug of the product. On Shopify this is the product handle.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/widgets/wishlists/default/toggle-item?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "productSlug": "string"
}'
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "added": true,
  "sharingEnabled": true,
  "multipleWishlists": true
}

    GET /widgets/wishlists

    List the current customer's wishlists. The customer parameters are optional here: with the publishable key alone it returns the store's wishlist settings and an empty list, which is how the widget renders for a shopper who is not signed in

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)

    The signed-in shopper's address. Leave it out for a shopper who is not signed in.

    timestampstring

    The Unix seconds the signature was made at. Required with customerEmail.

    signaturestring

    The HMAC of the email and timestamp. Required with customerEmail.

    Request
    curl \
  "https://api.cascade.dev/widgets/wishlists?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY"
    Response
    {
  "wishlists": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "itemsCount": 0,
      "shared": true,
      "shareUrl": "https://example.com",
      "isDefault": true,
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "sharingEnabled": true,
  "multipleWishlists": true
}

    POST /widgets/wishlists

    Create a new wishlist

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    namestringrequired

    What the customer called the wishlist.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/widgets/wishlists?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}

    GET /widgets/wishlists/{id}

    Get a wishlist with its items

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Request
    curl \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..."
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}

    PATCH /widgets/wishlists/{id}

    Update a wishlist's settings: its name or whether it is shared

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    namestring

    A new name for the wishlist.

    sharedboolean

    Turns the wishlist's share link on or off.

    isDefaultboolean

    Makes this wishlist the customer's default for one-click saves. Send false to leave the customer without a default.

    Request
    curl \
  -X PATCH \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "shared": true,
  "isDefault": true
}'
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}

    DELETE /widgets/wishlists/{id}

    Delete a wishlist

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Request
    curl \
  -X DELETE \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..."
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

    POST /widgets/wishlists/{id}/share-token

    Generate a new share token for a wishlist, invalidating the old share link

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000/share-token?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..."
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}

    POST /widgets/wishlists/{id}/items

    Add an item to a wishlist

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    productSlugstringrequired

    Slug of the product. On Shopify this is the product handle.

    productVariantIdstring (uuid) | null

    The variant the customer chose, or null to save the product as a whole.

    quantityinteger | null

    How many of this item the customer wants. Leave it out if they did not say.

    notestring

    A short note about this item, such as a size or color preference.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000/items?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "productSlug": "string",
  "productVariantId": "550e8400-e29b-41d4-a716-446655440000",
  "quantity": 0,
  "note": "string"
}'
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}

    PATCH /widgets/wishlists/{id}/items/{itemId}

    Update an item's quantity or note, or move it to another of the customer's wishlists

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist the item is on.

    itemIdstring (uuid)required

    The ID of the wishlist item.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    quantityinteger | null

    How many of this item the customer wants. Send null to clear it.

    notestring

    A short note about this item, such as a size or color preference. Send an empty string to clear it.

    wishlistIdstring (uuid)

    Moves the item to this wishlist, which must belong to the same customer. Any quantity or note edits in the same request are applied first. If the target list already has the same product and variant, the two entries merge: the target entry stays, keeps its quantity, and the moved item's note is appended to its note.

    Request
    curl \
  -X PATCH \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000/items/550e8400-e29b-41d4-a716-446655440000?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 0,
  "note": "string",
  "wishlistId": "550e8400-e29b-41d4-a716-446655440000"
}'
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}

    DELETE /widgets/wishlists/{id}/items/{itemId}

    Remove an item from a wishlist

    Path Parameters

    idstring (uuid)required

    The ID of the wishlist the item is on.

    itemIdstring (uuid)required

    The ID of the wishlist item.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Request
    curl \
  -X DELETE \
  "https://api.cascade.dev/widgets/wishlists/550e8400-e29b-41d4-a716-446655440000/items/550e8400-e29b-41d4-a716-446655440000?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..."
    Response
    {
  "wishlist": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "itemsCount": 0,
    "shared": true,
    "shareUrl": "https://example.com",
    "isDefault": true,
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z",
    "items": [
      {
        "id": "...",
        "productId": "...",
        "productVariantId": "...",
        "quantity": "...",
        "note": "...",
        "purchasedQuantity": "...",
        "createdAt": "...",
        "product": "...",
        "variant": "..."
      }
    ]
  },
  "sharingEnabled": true,
  "multipleWishlists": true
}