Wishlists

All endpoints require a valid JWT token in the Authorization header.

Get a wishlist

GET /v1/wishlists/{customerId}

Returns the customer’s wishlist. Supports pagination.

Query parameters

Parameter	Default	Description
limit	50	Number of items to return (max 200)
offset	0	Number of items to skip

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "productId": "8012345678",
        "variantId": "44012345678",
        "handle": "classic-white-tee",
        "addedAt": "2025-12-01T10:30:00.000Z"
      }
    ],
    "count": 1,
    "total": 1,
    "has_more": false
  }
}

Add an item

POST /v1/wishlists/{customerId}/items

Request body

{
  "product_id": "8012345678",
  "variant_id": "44012345678",
  "handle": "classic-white-tee"
}

Field	Required	Description
product_id	Yes	Shopify product ID
variant_id	No	Shopify variant ID. If omitted, the default variant is used
handle	No	Product handle (URL slug). Enables delete-by-handle for this item
metadata	No	Arbitrary JSON object (max 200 characters when serialized)

Note

Handles can go stale if a merchant renames a product. Prefer product_id for reliable deletion; handle is a convenience for storefront UX.

Response

{
  "ok": true,
  "data": {
    "item": {
      "productId": "8012345678",
      "variantId": "44012345678",
      "handle": "classic-white-tee",
      "addedAt": "2025-12-01T10:30:00.000Z"
    },
    "count": 5
  }
}

Remove an item

DELETE /v1/wishlists/{customerId}/items/{productId}

Response

{
  "ok": true,
  "data": {
    "removed": true,
    "count": 4
  }
}

Delete by handle

To delete by product handle instead of product ID, pass ?by=handle and use the handle as the path parameter:

DELETE /v1/wishlists/{customerId}/items/{handle}?by=handle

For example:

DELETE /v1/wishlists/12345/items/classic-white-tee?by=handle

This only works if the item was added with a handle field. If no matching handle is found, removed will be false.

Bulk remove items

Remove multiple items in a single call.

POST /v1/wishlists/{customerId}/items/bulk-delete

Request body

You can provide product_ids, handles, or both. At least one must be a non-empty array.

{
  "product_ids": ["8012345678", "8098765432"],
  "handles": ["vintage-denim-jacket"]
}

Field	Required	Description
product_ids	No*	Array of product IDs to remove
handles	No*	Array of product handles to remove

* At least one of product_ids or handles must be provided. Combined total cannot exceed 100.

Response

{
  "ok": true,
  "data": {
    "removed_count": 3,
    "count": 2
  }
}

Merge wishlists

Merge a guest (cookie) wishlist into a customer’s account wishlist. Call this when a customer logs in.

POST /v1/wishlists/{customerId}/merge

Request body

{
  "guest_items": [
    { "product_id": "8012345678", "handle": "classic-white-tee", "added_at": "2025-12-01T10:30:00.000Z" },
    { "product_id": "8098765432", "added_at": "2025-12-02T14:00:00.000Z" }
  ]
}

handle is optional on each item. If provided, it will be stored with the item for handle-based deletion.

Response

{
  "ok": true,
  "data": {
    "merged_count": 2,
    "items": [
      {
        "productId": "8012345678",
        "handle": "classic-white-tee",
        "addedAt": "2025-12-01T10:30:00.000Z"
      }
    ],
    "count": 7
  }
}

Bulk import

Import wishlist items for multiple customers in a single call. Requires Growth plan or above.

POST /v1/wishlists/import

Request body

{
  "items": [
    { "customer_id": "12345", "product_id": "8012345678", "handle": "classic-white-tee" },
    { "customer_id": "12345", "product_id": "8098765432" },
    { "customer_id": "67890", "product_id": "8012345678", "variant_id": "44012345678" }
  ],
  "dry_run": false
}

Field	Required	Description
items[].customer_id	Yes	Shopify customer ID
items[].product_id	Yes	Shopify product ID
items[].variant_id	No	Shopify variant ID
items[].handle	No	Product handle
items[].added_at	No	ISO 8601 timestamp. Defaults to import time if omitted
items[].metadata	No	Arbitrary JSON object
dry_run	No	If true, validates without writing. Defaults to false

Max 500 items per call. Duplicates are skipped automatically.

Response

{
  "ok": true,
  "data": {
    "customers": 2,
    "imported": 3,
    "skipped": 0,
    "dry_run": false
  }
}

Share a wishlist

Generate a shareable link for a customer’s wishlist. Requires Starter plan or above.

GET /v1/wishlists/{customerId}/share

Response

{
  "ok": true,
  "data": {
    "share_url": "https://wishlist-api.simplersuite.co/v1/wishlists/shared/abc123def456",
    "expires_at": "2026-01-15T00:00:00.000Z"
  }
}

Get a shared wishlist

Fetch a wishlist by its share token. No authentication required.

GET /v1/wishlists/shared/{shareToken}

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "productId": "8012345678",
        "variantId": "44012345678",
        "addedAt": "2025-12-01T10:30:00.000Z"
      }
    ],
    "count": 3,
    "created_at": "2025-12-15T00:00:00.000Z",
    "expires_at": "2026-01-15T00:00:00.000Z"
  }
}