Wishlist Items
Add, remove, list, and check wishlist items.
All item endpoints require an identity with at least customerId or sessionId.
customerId is the numeric Shopify customer id as a string.
Authentication is required.
Identity object
{
"customerId": "8769049329896",
"sessionId": "guest-session-id",
"email": "customer@example.com",
"firstName": "Jane",
"lastName": "Doe",
"device": "desktop",
"locale": "en"
}Add item
POST /item/add
Request
{
"identity": {
"customerId": "8769049329896",
"sessionId": null,
"email": "customer@example.com",
"firstName": "Jane",
"lastName": "Doe",
"device": "desktop",
"locale": "en"
},
"productId": "12321312412",
"variantId": null,
"productTitle": "Sunglasses",
"variantTitle": null,
"productHandle": "sunglasses",
"image": "https://cdn.example.com/image.jpg",
"price": "49.00",
"compareAt": "69.00",
"currencyCode": "USD",
"countryCode": "US",
"inventoryAvailable": true,
"properties": { "custom": "value" },
"quantity": 1,
"source": "pdp"
}Payload
| Field | Type | Required | Notes |
|---|---|---|---|
| identity | Identity | yes | Must include at least customerId or sessionId. |
| productId | string | yes | Min length 1. |
| variantId | string or null | no | nullish accepted. |
| productTitle | string | yes | Min length 1. |
| variantTitle | string or null | no | nullish accepted. |
| productHandle | string | yes | Min length 1. |
| image | string | yes | Min length 1. |
| price | string | yes | |
| compareAt | string | yes | |
| currencyCode | string | no | 2-3 chars. |
| countryCode | string | no | Exactly 2 chars. |
| inventoryAvailable | boolean | yes | |
| properties | unknown | no | |
| quantity | number | yes | Integer. |
| source | enum | no | pdp, collection, cart, wishlist, email, other, pdpSmartSave. Default: pdp. |
Response
{
"profileId": "cuid...",
"itemId": "cuid...",
"productId": "12321312412",
"variantId": null,
"quantity": 1
}Remove item
POST /item/remove
Request
{
"identity": {
"customerId": "8769049329896",
"sessionId": null,
"device": "desktop",
"firstName": null,
"lastName": null,
"locale": "en"
},
"productId": "12321312412",
"variantId": null,
"event": null
}Response
{
"profileId": "cuid...",
"removed": true,
"productId": "12321312412",
"variantId": null
}List items
POST /item/list
Request
{
"identity": {
"customerId": "8769049329896",
"sessionId": null,
"device": "desktop",
"firstName": null,
"lastName": null,
"locale": "en"
},
"includePublicCount": false
}Response
{
"profileId": "cuid...",
"items": [
{
"id": "cuid...",
"profileId": "cuid...",
"shop": "example.myshopify.com",
"productId": "12321312412",
"variantId": null,
"productTitle": "Sunglasses",
"variantTitle": null,
"productHandle": "sunglasses",
"image": "https://cdn.example.com/image.jpg",
"price": "49.00",
"compareAt": "69.00",
"properties": { "custom": "value" },
"quantity": 1,
"source": "pdp",
"lastInventory": null,
"lastPriceDropNotifiedPrice": null,
"lastPriceDropNotifiedAt": null,
"lastBackInStockNotifiedAt": null,
"lastLowStockNotifiedAt": null,
"addedAt": "2026-02-07T10:00:00.000Z",
"updatedAt": "2026-02-07T10:00:00.000Z"
}
]
}Item status
POST /item/status
Request
{
"identity": {
"customerId": "8769049329896",
"sessionId": null,
"device": "desktop",
"firstName": null,
"lastName": null,
"locale": "en"
},
"productId": "12321312412",
"variantId": null,
"includePublicCount": true
}Response
{
"profileId": "cuid...",
"exists": true,
"publicCount": 24
}