Back to Home

Wishlist API

The Wishlist API enables the management of customer wishlists.

In most situations, The Wishlist platform will be the master data source for Wishlists, as it is able to manage wishlist information from multiple sources (e.g. website or physical stores); then trigger events based on saved wishlist items; and send wishlist information to 3rd party systems such as marketing automation platforms like Emarsys, Klaviyo and DotDigital.

One customer may have mulitple wishlists. You can only create a wishlist for a valid customer.

A wishlist is created ‘empty’ and items added later, either one by one, or multiple items can be added at the same time.

Wishlist items should be saved at the variant level, rather than the parent product level, as the customer will typically be wishlisting a variant, not a product.

---

Wishlist API

• Wishlist API
  • General Notes
  • Representations
    • Wishlist Request
    • Wishlist Response
    • WishlistItem Request
    • WishlistItem Product
    • AttributeGroups
    • AttributeGroup
    • WishlistItem Response
• Endpoints
  • Wishlist
    • Ceate a wishlist
  • Update a wishlist
    • Update Wishlist By ID
    • Update Wishlist By Ref
    • Update wishlist by either ID or Ref
  • GET Wishlist
    • Get Wishlist by Id
    • Get Wishlist by Wishlist Reference
    • Get Wishlist by id/wishlistRef
  • Get customer wishlists
  • Delete Wishlist
    • Delete Wishlist by ID/Ref
  • Delete Wishlist by ID
    • Delete Wishlist by Ref
  • Get wishlist interactions
• WishlistItem
  • Create a Wishlist Item
  • Add multple Wishlist Items
  • Update WishlistItems
    • Update a Wishlist Item
    • Update a Wishlist Item By Ref
    • Update a Wishlist Item By Id
  • Get Wishlist Items
    • Get all Items in a Wishlist by Wishlist Id
    • Get Wishlist Item by Item Id
    • Get Wishlist Item by Item Ref
  • Delete Wishlist Item
    • Delete Wishlist Item by Id
    • Delete Wishlist Item by itemRef

General Notes

Wishlist endpoints must be prefixed with /services/wsservice for example create customer endpoint is /api/wishlists, when you invoke the api it will be /services/wsservice/api/wishlists

Production api endpoint https://api.au-aws.thewishlist.io/services/wsservice/api/wishlists

Representations

All requests or responses are JSON objects

Wishlist Request

Field	Type	Description
customerId	string	TWC generated unique customer identifier. Either customerId or customerRef is mandatory when creating a wishlist
customerRef	string	Retailer’s own unique customer identifier. Either customerId or customerRef is mandatory when creating wishlist
description	string	Wishlist description. This field is optional. It may be useful in social shopping scenarios
name	string	The Wishlist name provided by the customer. Name is mandatory
wishlistRef	string	This is an optional reference identifier given to the wishlist by the retailer. This field may be used to GET/UPDATE/DELETE the wishlist. It is likely most useful for integrating with existing ecommerce wishlist systems.
isPrivate	boolean	Indicates the wishlist is private to customer
attributeGroups	AttributeGroups	This field may be used to add additional attributes to the wishlist. This field is in general available on most entitiesin The Wishlist platform. “attributeGroups”: {  “extra_attribute_group1”: {   “attributes”: {   “wishlist_origin”: “app”,   “ecommerce_wishlist_id”: “ecommerce system generated id”,     },   “description”: “any additional attribute you want to add to wishlist”  },  “retailer_defined_name_of_group”: {   “attributes”: {   “retailer_defined_attribute1”: “user defined attribute value”,   “another_attribute”: “another value”   },   “description”: “retailer defined properties and its values, flexible data model to add additional properties.”  } }

Wishlist Response

Field	Type	Description
id	string	TWC generated unique wishlist identifier.
customerId	string	TWC unique customer identifier.
customerRef	string	Retailer’s own unique identifier of customer.
description	string	Wishlist description.
deleted	string	Indicates if the wishlist has been deleted
name	string	Wishlist name
wishlistRef	string	This is a reference identifier given to a wishlist by retailer. This field may be used to GET/UPDATE/DELETE the wishlist. It is likely most useful when integrating to existing ecoommerce wishlist systems.
isPrivate	boolean	Indicates the wishlist is private to customer
attributeGroups	AttributeGroups	This field may be used to add additional attributes to the wishlist. This field is in general available on most entitiesin The Wishlist platform. “attributeGroups”: {  “extra_attribute_group1”: {   “attributes”: {   “wishlist_origin”: “app”,   “ecommerce_wishlist_id”: “ecommerce system generated id”,     },   “description”: “any additional attribute you want to add to wishlist”  },  “retailer_defined_name_of_group”: {   “attributes”: {   “retailer_defined_attribute1”: “user defined attribute value”,   “another_attribute”: “another value”   },   “description”: “retailer defined properties and its values, flexible data model to add additional properties.”  } }

WishlistItem Request

Field	Type	Description
addedFromCart	boolean	Indicates the item was added from cart. Developers should set this flag if the item was added to the wishlist directly fom the shopping cart
addedByStaff	boolean	This optional field indicates the item was added by a staff member in a store. Should be used in conjunction with staffRef and locationRef, which stores the retailer’s store identifier. Developers should set this flag if the item was added to the wishlist by a staff member to enable drill down reporting and staff attribution of interactions
disableNotification	boolean	Disable notifications for this wishlist item.
wishlistId	string	TWC generated unique identifier for the wishlist to which the item is being added. Either wishlistId or wishlistRef is mandatory when creating a wishlist item.
wishlistRef	string	The reatailer assigned unique reference identifier for the wishlist. Either wishlistId or wishlistRef is mandatory when creating a wishlist item.
wishlistItemRef	string	Retailer assigned unique reference identifier of the wishlist item.
prerelease	boolean	Indicates that the customer is registering interest to a pre-released product. Used in the Register Interest notification
purchasedAndRemoved	boolean	This parameter is used to differentiate and identify the wishlist items removed after sale conversions. This can be set manually or automated based on a configuration.
notifyMe	boolean	This parameter is used to notify the customer once the wishlisted product comes in stock
product	Product	Represents the item product. This is a mandatory field.
staffRef	string	The reference number of the staff that added the wishlist item for the customer. Should be used in conjunction with addedByStaff and locationRef
locationRef	string	The reference number for the location where the item was added to the wishlist (typically a store identifier). Should be used in conjunction with addedByStaff and staffRef
attributeGroups	AttributeGroups	This field may be used to add additional attributes to the wishlist. This field is in general available on most entitiesin The Wishlist platform. “attributeGroups”: {  “extra_attribute_group1”: {   “attributes”: {   “wishlist_item_origin”: “mobile_app”,   “ecommerce_wishlist_item_id”: “ecommerce system generated id”,     },   “description”: “any additional attribute you want to add to wishlist”  },  “retailer_defined_name_of_group”: {   “attributes”: {   “retailer_defined_attribute1”: “user defined attribute value”,   “another_attribute”: “another value”   },   “description”: “retailer defined properties and its values, flexible data model to add additional properties.”  } }

WishlistItem Product

Field	Type	Description
productId	string	This is the TWC generated product identifier. Either productId or productRef is mandatory when creating a wishlist item.
productRef	string	This is the retailer assigned product reference identifier. Either productId or productRef is mandatory when creating a wishlist item. Please note that TWC does not validate the existance of a product when adding to the Wishlist. This allows you to add an item that may not have yet been synched to the product catalogue. However, notifications will not trigger if a product/variant does not exist.
selectedVariantId	string	This is the TWC assigned variant identifier. Either selectedVariantId or selectedVariantRef is mandatory when creating a wishlist item.
selectedVariantRef	string	This is the retailer assigned variant reference identifier. Either selectedVariantId or selectedVariantRef is mandatory when creating a wishlist item. Please note that TWC does not validate the existance of a variant when adding to the Wishlist. This allows you to add an item that may not have yet been synched to the product catalogue. However, notifications will not trigger if a product/variant does not exist.
oldVariantId	string	When updating a wishlist item to another variant using the ID, oldVariantId field is mandatory, to switch to another variant. This is TWC generated unique identifier.
oldVariantRef	string	When updating a wishlist item to another variant using the variantRef, then oldVariantRef field is mandatory, to switch to another variant.

–>

AttributeGroups

Field	Type	Description
attributeGroup	AttributeGroup	This field holds the groups of attributes as a map of <String, AttributeGroup>. e.g.: {  “extra_attribute_group1”: {   “attributes”: {   “wishlist_origin”: “app”,   “ecommerce_wishlist_id”: “ecommerce system generated id”,     },   “description”: “any additional attribute you want to add to wishlist”  },  “retailer_defined_name_of_group”: {   “attributes”: {   “retailer_defined_attribute1”: “user defined attribute value”,   “another_attribute”: “another value”   },   “description”: “retailer defined properties and its values, flexible data model to add additional properties.”  } }

AttributeGroup

Field	Type	Description
attributes	map	This field holds map of attributes as a map of <string, string> e.g.: {   “wishlist_origin”: “app”,   “ecommerce_wishlist_id”: “ecommerce system generated id”,     }
description	string	This field is a short description about the attributes captured under field attributes. This will only be used in the backoffice tools.

WishlistItem Response

Field	Type	Description
id	string	This is the TWC generted unique identifier for the wishlist item.
addedFromCart	boolean	Indicates the item was added from a shopping cart.
addedByStaff	boolean	This optional field indicates the item was added by a staff member in a store. Should be used in conjunction with staffRef and locationRef, which stores the retailer’s store identifier. Developers should set this flag if the item was added to the wishlist by a staff member to enable drill down reporting and staff attribution of interactions
disableNotification	boolean	Disable notifications for this wishlist item.
wishlistId	string	TWC generated unique identifier of wishlist, to which the item is being added. Either wishlistId or wishlistRef is mandatory when creating a wishlist item.
wishlistRef	string	reatailer assigned unique identifier for the wishlist. Either wishlistId or wishlistRef is mandatory when creating a wishlist item.
wishlistItemRef	string	reatailer assigned unique identifier for the wishlist item.
prerelease	boolean	Indicates that customer is registering interest to a pre release item. Used in the register interest notification
purchased	boolean	Indicates that the item has been purchased.
purchasedAndRemoved	boolean	This parameter is used to differentiate and identify the wishlist items removed after sale conversions. This can be set manually or automated based on a configuration.
notifyMe	boolean	Indicates notifyMe flag
purchasedDate	boolean	The date on which item was purchased. If orders are pushed to TWC, TWC will mark the item as purchased.
product	Product	This field represents the field being added to item product
staffRef	string	The reference number of the staff that added the wishlist item for the customer. Should be used in conjunction with addedByStaff and locationRef
locationRef	string	The reference number for the location where the item was added to the wishlist (typically a store identifier). Should be used in conjunction with addedByStaff and staffRef
attributeGroups	object	This field may be used to add additional attributes to the wishlist. This field is in general available on most entitiesin The Wishlist platform. “attributeGroups”: {  “extra_attribute_group1”: {   “attributes”: {   “wishlist_item_origin”: “mobile_app”,   “ecommerce_wishlist_item_id”: “ecommerce system generated id”,     },   “description”: “any additional attribute you want to add to wishlist”  },  “retailer_defined_name_of_group”: {   “attributes”: {   “retailer_defined_attribute1”: “user defined attribute value”,   “another_attribute”: “another value”   },   “description”: “retailer defined properties and its values, flexible data model to add additional properties.”  } }

Endpoints

Wishlist

Ceate a wishlist

Creates a new wishlist. The Customer must be created before creating their wishlist(s).

Endpoint	/api/wishlists
Method	POST
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Sample Request:

{
  "attributeGroups": {
    "extra_attribute_group1": {
      "attributes": {
        "wishlist_origin": "app",
        "ecommerce_wishlist_id": "ecommerce system generated id",        
      },
      "description": "any additional attribute you want to add to wishlist"
    },
    "retailer_defined_name_of_group": {
      "attributes": {
        "retailer_defined_attribute1": "user defined attribute value",
        "another_attribute": "another value"
      },
      "description": "retailer defined properties and its values, flexible data model to add additional properties."
    }
  },
  "customerId": "twc-generated-customer-id", //either customerId or customerRef is mandatory
  "customerRef": "retailers_customer_id",
  "description": "wishlists description", // This field may not be used for private wishlist scenario. This field however may be key in a social shopping scenario.
  "isPrivate": "true", //marking the wishlist private. not a mandatory field.
  "name": "wishlist name",
  "wishlistRef": "retailers wishlist id" // this is not a mandatory field. However, if set could be used to GET/UDPATE/DELETE wishlist using this reference Id.
}

Response - 201 (created)

{
    "id": "2cd4e650-8f00-4d13-ba46-831c2cf29211",
    "wishlistRef": "1111111",
    "name": "An awesome wishlist",
    "customerId": "93847020-4c74-4239-9310-58d1c91cc1a7",
    "customerRef": "CUSTOMER1234",
    "deleted": false,
    "createdTime": "2023-05-01T00:02:38.048171Z",
    "modifiedTime": "2023-05-01T00:02:38.048174Z",
    "attributeGroups": {
        "pos_attributes": {
            "description": "POS related wishlist information",
            "attributes": {
                "created_in": "POS",
                "staff_id": "STAFF111",
                "POS_ref": "POS12341234",
                "store_id": "STORE111"
            }
        }
    }
}

HTTP Status Code:

- 200 OK
- 201 Created
- 204 Deleted
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found
- 405 Invalid input

Update wishlist by either ID or Ref

Used to update any metadata about a wishlist, for example, attribute groups, staff/store ID or wishlist name. This API is NOT used to update items on the wishlist You can update by internal Wishlist ID or wishlistRef (the retailer’s unique wishlist identifier).

Endpoint	/api/wishlists
Method	PUT
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Sample Request:

{
  "id":"twc-generated-wishlist-id", // Either id or wishlistRef is mandatory to update a wishlist using this service.
  "attributeGroups": {
    "extra_attribute_group1": {
      "attributes": {
        "wishlist_origin": "app",
        "ecommerce_wishlist_id": "ecommerce system generated id",        
      },
      "description": "any additional attribute you want to add to wishlist"
    },
    "retailer_defined_name_of_group": {
      "attributes": {
        "retailer_defined_attribute1": "user defined attribute value",
        "another_attribute": "another value"
      },
      "description": "retailer defined properties and values, flexible data model to add additional properties."
    }
  },
  "customerId": "twc-generated-customer-id", //either customerId or customerRef is mandatory
  "customerRef": "retailers_customer_id",
  "description": "wishlists description", // This field may be useful in a social shopping scenario.
  "isPrivate": "true", //marking the wishlist private. not a mandatory field.
  "name": "wishlist name",
  "wishlistRef": "retailers wishlist id" // Either id or wishlistRef is mandatory to update a wishlist using this service.
}

Response - 200 (OK Updated)

{
  "id": "2cd4e650-8f00-4d13-ba46-831c2cf29211",
  "attributeGroups": {
    "extra_attribute_group1": {
      "attributes": {
        "wishlist_origin": "app",
        "ecommerce_wishlist_id": "ecommerce system generated id",        
      },
      "description": "any additional attribute you want to add to wishlist"
    },
    "retailer_defined_name_of_group": {
      "attributes": {
        "retailer_defined_attribute1": "user defined attribute value",
        "another_attribute": "another value"
      },
      "description": "retailer defined properties and values, flexible data model to add additional properties."
    }
  },
  "wishlistRef": "17949",
  "name": "Test wishlist 17949 creation",
  "customerId": "93847020-4c74-4239-9310-58d1c91cc1a7",
  "customerRef": "CUST16003",
  "deleted": false,
  "createdTime": "2023-05-01T00:02:38.048171Z",
}

HTTP Status Codes

- 200 OK
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Get Wishlist by id or wishlistRef

Retrieves the wishlist and the wishlist items that belongs to the given wishlist Id or wishlistRef. If the wishlist does not exist, this method returns a ResourceNotFound error.

The returned item array is paginated - 20 default (50 maximum). The API will respond with the item count in the page, and the itemID the for the last item (lastitemID) returned for that response, which should then be used for the subsequent API call to retrieve the next page.

Endpoint	/api/wishlists/
Method	GET
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Query Parameters	Description
id	This is the TWC system generated unique wishlist identifier. e.g: 67ccc612-0f1b-4d9d-b69e-d43511c6782d. The API will query the database for wishlists by ID.
wishlistRef	This is the retailer assigned unique wishlist reference identifier. e.g: WISH0001. The API will query the database for wishlists by reference value.
pageSize	Determines the number of wishlist items returned in the API response. Default page size is 20 and max is 50.
lastItemId	Determines which items to return. API returns wishlist items in the ascending order of their TWC generated wishlist ID. This parameter will inform the API to respond with items that have ID greater than, but excluding the value provided.

When provided with valid inputs, API responds with a application/json type content.

sample response - 200 (OK)

{
    "id": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "wishlistRef": "24639",
    "name": "Test wishlist 24639 creation",
    "customerId": "93847020-4c74-4239-9310-58d1c91cc1a7",
    "customerRef": "CUST16003",
    "deleted": false,
    "createdTime": "2023-05-01T02:37:00.543594Z",
    "modifiedTime": "2023-05-01T02:37:00.543597Z",
    "lastEvaluatedItemId": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "itemCount": 1,
    "wishlistItems": [
        {
            "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
            "wishlistItemRef": "WI200013716",
            "purchased": false,
            "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
            "product": {
                "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
                "productRef": "100019951",
                "selectedVariantId": "5396d084-4346-44d2-9d87-b2015c1d7b42",
                "selectedVariantRef": "4690"
            },
            "createdTime": "2023-05-01T02:37:22.407387Z",
            "modifiedTime": "2023-05-01T02:37:22.407390Z",
            "attributeGroups": {
                "POS_attributes": {
                    "description": "POS related attidional information",
                    "attributes": {
                        "POS_ref": "POS001",
                        "store_id": "STORE001"
                    }
                }
            },
            "addedFromCart": false,
            "prerelease": false,
            "disableNotification": false
        }
    ],
    "attributeGroups": {
        "POS_attributes": {
            "description": "POS related attidional information",
            "attributes": {
                "STAFF_ID": "STAFF001",
                "POS_ref": "POS001",
                "store_id": "STORE001"
            }
        }
    }
}

HTTP Status Code:

- 200 OK
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Get wishlist(s) by customer id or customerRef

Returns the collection of wishlists that belong to either the internal TWC customer identifier, or the retailer’s own customerRef.

The returned list is paginated - 20 default (50 maximum). The API will respond with the number of wishlists returned in the page, and the wishlistID for the for the last wishlist returned for that response, which should then be used for the subsequent API call to retrieve the next page.

If no wishlists exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlists/lookup
Method	GET
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Query Parameters	Description
customerId	This is the TWC generated unique customer identifier. e.g: 67ccc612-0f1b-4d9d-b69e-d43511c6782d. API will query database for wishlists that belong to customer with the given ID.
customerRef	This is the retailer assigned unique customer reference identifier. e.g: CUST1111. API will query database for wishlists that belong to customer with the given reference value.
pageSize	Determines the number of wishlist items returned in the API response. Default page size is 20 and max is 50.
lastItemId	Determinse which items to return. API returns wishlist items in the ascending order of their TWC generated wishlist ID. This parameter will inform API to respond items with ID greater than, but excluding the value provided.

Response - 200 (OK)

{
    "wishlistCount": 2,
    "lastEvaluatedWishlistId": "2cd4e650-8f00-4d13-ba46-831c2cf29211",
    "wishlist": [
        {
            "id": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
            "wishlistRef": "24639",
            "name": "Test wishlist 24639 creation",
            "customerId": "93847020-4c74-4239-9310-58d1c91cc1a7",
            "customerRef": "CUST16003",
            "deleted": false,
            "createdTime": "2023-05-01T02:37:00.543594Z",
            "modifiedTime": "2023-05-01T02:37:00.543597Z",
            "lastEvaluatedItemId": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
            "itemCount": 1,
            "wishlistItems": [
                {
                    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
                    "wishlistItemRef": "WI200013716",
                    "purchased": false,
                    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
                    "product": {
                        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
                        "productRef": "100019951",
                        "selectedVariantId": "5396d084-4346-44d2-9d87-b2015c1d7b42",
                        "selectedVariantRef": "4690"
                    },
                    "createdTime": "2023-05-01T02:37:22.407387Z",
                    "modifiedTime": "2023-05-01T02:37:22.407390Z",
                    "attributeGroups": {
                        "POS_attributes": {
                            "description": "POS related attidional information",
                            "attributes": {
                                "POS_ref": "POS001",
                                "store_id": "STORE001"
                            }
                        }
                    },
                    "addedFromCart": false,
                    "prerelease": false,
                    "disableNotification": false
                }
            ],
            "attributeGroups": {
                "POS_attributes": {
                    "description": "POS related attidional information",
                    "attributes": {
                        "STAFF_ID": "STAFF001",
                        "POS_ref": "POS001",
                        "store_id": "STORE001"
                    }
                }
            }
        },
        {
            "id": "2cd4e650-8f00-4d13-ba46-831c2cf29211",
            "wishlistRef": "17949",
            "name": "Test wishlist 17949 creation",
            "customerId": "93847020-4c74-4239-9310-58d1c91cc1a7",
            "customerRef": "CUST16003",
            "deleted": false,
            "createdTime": "2023-05-01T00:02:38.048171Z",
            "modifiedTime": "2023-05-01T00:02:38.048174Z",
            "wishlistItems": [],
            "attributeGroups": {
                "POS_attributes": {
                    "description": "POS related attidional information",
                    "attributes": {
                        "STAFF_ID": "STAFF001",
                        "POS_ref": "POS001",
                        "store_id": "STORE001"
                    }
                }
            }
        }
    ]
}

HTTP Status Codes

- 200 OK
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Delete Wishlist

Delete Wishlist by wishlist ID or wishlistRef

Delete Wishlist marks the wishlist as deleted and produces an HTTP response confirming the action. The Wishlist is identified either by the TWC Internal wishlist identifier or the retailers own wishlistRef. The wishlists are actually retained in the system for reporting purposes, but are de-identified so cannot be linked back to the customer.

If the wishlist does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlists/
Method	DELETE
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Query Parameters	Description
id	This is the TWC system generated unique wishlist identifier. e.g: 67ccc612-0f1b-4d9d-b69e-d43511c6782d. API will remove the wishlists for the given ID. Either id or wishlistRef must be provided with this API call.
wishlistRef	This is the retailers assigned unique wishlist reference identifier. e.g: WISH0001. The API will remove the wishlists matching the given retailer wishlist reference ID. Either id or wishlistRef must be provided with this API call.

Response - 204 (Deleted)

HTTP Status Code

- 204 Deleted
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Delete Wishlist(s) by customer ID or customerRef

Delete Wishlist by customer marks the specified customer’s wishlist(s) as deleted and produces an HTTP response confirming the action. The customer is identified either by the TWC Internal customer identifier or the retailers own customerRef. All of the customer wishlists are deleted. The wishlists are actually retained in the system for reporting purposes, but are de-identified so cannot be linked back to the customer.

If the wishlist does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlists/customer
Method	DELETE
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Query Parameters	Description
customerId	This is the TWC system generated unique customer identifier. e.g: bbccc612-0f1b-4d9d-b69e-d43511c6782d. API will remove the wishlists for the given ID. Either customerId or customerRef must be provided with this API call.
customerRef	This is the retailers assigned unique customer reference identifier. e.g: CUST001. The API will remove the wishlists matching the given customer reference number. Either customerId or customerRef must be provided with this API call.

Response - 204 (Deleted)

HTTP Status Code

- 204 Deleted
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

WishlistItem

Create a Wishlist Item

Adds a single wishlist item into an existing wishlist. The wishlist can be identified by either the TWC internal identifier, or the wishlistRef, which is the retailer’s own wishlist identifier.

To create a wishlist item, you need to provide either of the following:

• BOTH the TWC product identifier AND TWC variant identifer (i.e. the TWC productID and variantID which you can get from TWC in a prior call), OR
• BOTH your own internal product identifier AND variant identifer (i.e. productRef and variantRef).

Endpoint	/api/wishlist/items
Method	POST
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Sample Request:

{
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "wishlistItemRef": "WISHITEM1111",
    "product":
    {
        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
        "selectedVariantId": "5396d084-4346-44d2-9d87-b2015c1d7b42"
    },
    "attributeGroups":
    {
        "cart_info":
        {
            "attributes": {
                "cart_id": "CART1111",
                "channel": "mobile-app"
            },
            "description": "cart related attributes"
        }
    },
    "notifyMe" : true
}

Response - 201 (created)

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistItemRef": "WI200013716",
    "purchased": false,
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
        "productRef": "100019951",
        "selectedVariantId": "5396d084-4346-44d2-9d87-b2015c1d7b42",
        "selectedVariantRef": "4690"
    },
    "createdTime": "2023-05-01T02:37:22.407387Z",
    "modifiedTime": "2023-05-01T02:37:22.407390Z",
    "attributeGroups": {
        "cart_info":
        {
            "attributes": {
                "cart_id": "CART1111",
                "channel": "mobile-app"
            },
            "description": "cart related attributes"
        }
    },
    "addedFromCart": false,
    "prerelease": false,
    "disableNotification": false,
    "notifyMe" : true
}

HTTP Status Code:

- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found
- 405 Invalid input

Add multple Wishlist Items using wishlist ID or wishlistRef

Add multiple items to an existing wishlist. Please provide either wislist ID or wishlistRef.

Endpoint	/api/wishlist/add-items
Method	POST
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Sample Request

{
  "itemId": [
    {
      "addedFromCart": true,
      "attributeGroups": {
        "additionalProp1": {
          "attributes": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "description": "string"
        }
      },
      "disableNotification": true,
      "locationRef": "string",
      "prerelease": true,
      "productId": "string",
      "selectedVariantId": "string",
      "wishlistItemRef": "string",
    }
  ],
  "itemRef": [
    {
      "addedFromCart": true,
      "attributeGroups": {
        "additionalProp1": {
          "attributes": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "description": "string"
        }
      },
      "disableNotification": true,
      "locationRef": "string",
      "prerelease": true,
      "productRef": "string",
      "selectedVariantRef": "string",
      "wishlistItemRef": "string"
    }
  ],
  "wishlistRef": "string"
}

Status Codes

- 202 Accepted
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden 
- 409 Conflict

Update a Wishlist Item By Wishlist item Id

Update a wishlist item (for example to change the selected variant if the size or colour of the product is updated). Developer must supply the wishlist Item Ref. Note that itemRef is the client’s unique identifier for a wishlist item associated with a single wishlist item. It is NOT the productRef, which typically could be the retailer’s product SKU.

If the variant is being changed, then the original variant ID (TWC internal ID) must also be provided.

Endpoint	/api/wishlist/items/ref={ref}
Method	PUT
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
path variable	ref ref is the retailer assigned unique wishlist item reference.
How to get access token	Tenant Authentication

Sample Request:

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "",
        "selectedVariantId": "",
        "oldVariantId": "5396d084-4346-44d2-9d87-b2015c1d7b42"
    },
    "attributeGroups": {
        "cart_attributes": {
            "attributes": {
                "cart_ref": "CART00111",
                "channel": "web"
            },
            "description": "cart info"
        }
    },
    "notifyMe" : true
}

Response - 200 (OK Updated)

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistItemRef": "WI200013716",
    "purchased": false,
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
        "productRef": "100019951",
        "selectedVariantId": "3a40289c-d56b-49f2-b0f7-d3383a36bc80",
        "selectedVariantRef": "6665"
    },
    "createdTime": "2023-05-01T02:37:22.407387Z",
    "modifiedTime": "2023-05-01T04:57:45.835957Z",
    "attributeGroups": {
        "cart_attributes": {
            "description": "cart info",
            "attributes": {
                "cart_ref": "CART00111",
                "channel": "web"
            }
        },
        "POS_attributes": {
            "description": "POS related attidional information",
            "attributes": {
                "POS_ref": "POS001",
                "store_id": "STORE001"
            }
        }
    },
    "addedFromCart": false,
    "prerelease": false,
    "disableNotification": false,
    "notifyMe" : true
}

HTTP Status Code:

- 200 OK
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Update a Wishlist Item By wishlist item Id

Update a wishlist item (for example to change the selected variant). Developer must supply the item ID. Note, this is the TWC wishlistItem identifier, NOT the productID or varantID.

If the variant is being changed, then the original variant ID (TWC internal ID) must also be provided.

Endpoint	/api/wishlist/items/id={id}
Method	PUT
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
path variable	id id is the TWC generated unique identifier of the wishlist item.
How to get access token	Tenant Authentication

Sample Request:

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "",
        "selectedVariantId": "",
        "oldVariantId": "5396d084-4346-44d2-9d87-b2015c1d7b42"
    },
    "attributeGroups": {
        "cart_attributes": {
            "attributes": {
                "cart_ref": "CART00111",
                "channel": "web"
            },
            "description": "cart info"
        }
    },
    "notifyMe" : true
}

Response - 200 (OK Updated)

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistItemRef": "WI200013716",
    "purchased": false,
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
        "productRef": "100019951",
        "selectedVariantId": "3a40289c-d56b-49f2-b0f7-d3383a36bc80",
        "selectedVariantRef": "6665"
    },
    "createdTime": "2023-05-01T02:37:22.407387Z",
    "modifiedTime": "2023-05-01T04:57:45.835957Z",
    "attributeGroups": {
        "cart_attributes": {
            "description": "cart info",
            "attributes": {
                "cart_ref": "CART00111",
                "channel": "web"
            }
        },
        "POS_attributes": {
            "description": "POS related attidional information",
            "attributes": {
                "POS_ref": "POS001",
                "store_id": "STORE001"
            }
        }
    },
    "addedFromCart": false,
    "prerelease": false,
    "disableNotification": false,
    "notifyMe" : true
}

HTTP Status Code:

- 200 OK
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Get all Items in a Wishlist by Wishlist Id

Returns a list of all wishlist items belonging to the given wishlist identifier (TWC internal identifier).

Results are paginated, page size is 20, maximum 50. If the item does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlist/items
Method	GET
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
How to get access token	Tenant Authentication

Query Parameters	What is it for ?
id	This is the TWC system generated unique wishlist identifier. e.g: 67ccc612-0f1b-4d9d-b69e-d43511c6782d. The API will query the database for wishlists by ID.
wishlistRef	This is the retailer assigned unique wishlist reference identifier. e.g: WISH0001. The API will query the database for wishlists by the reference value provided.
pageSize	Determines the number of wishlist items returned in the API response. Default page size is 20 and max is 50.
lastItemId	Determines which items to return. API returns wishlist items in the ascending order of their TWC generated wishlist ID. This parameter will inform the API to respond with the items with an identifier greater than, but excluding the value provided.

Sample Response - 200 (OK)

{
    "itemCount": 2,
    "lastEvaluatedItemId": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistItems": [
        {
            "id": "ffe332f6-7f28-4dc0-a398-5c6f93b0d7df",
            "wishlistItemRef": "WI2000131662",
            "purchased": false,
            "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
            "product": {
                "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
                "productRef": "100019951",
                "selectedVariantId": "b72e501d-d87a-40bb-b0bb-2d4c3cbb4f0a",
                "selectedVariantRef": "9561"
            },
            "createdTime": "2023-05-01T04:40:44.106530Z",
            "modifiedTime": "2023-05-01T04:40:44.106530Z",
            "attributeGroups": {
                "cart_info": {
                    "description": "cart related attributes",
                    "attributes": {
                        "cart_id": "CART1111",
                        "channel": "mobile-app"
                    }
                }
            },
            "addedFromCart": true,
            "prerelease": false,
            "disableNotification": false,
            "notifyMe" : true
        },
        {
            "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
            "wishlistItemRef": "WI200013716",
            "purchased": false,
            "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
            "product": {
                "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
                "productRef": "100019951",
                "selectedVariantId": "3a40289c-d56b-49f2-b0f7-d3383a36bc80",
                "selectedVariantRef": "6665"
            },
            "createdTime": "2023-05-01T02:37:22.407387Z",
            "modifiedTime": "2023-05-01T04:57:45.835957Z",
            "attributeGroups": {
                "cart_attributes": {
                    "description": "cart info",
                    "attributes": {
                        "cart_ref": "CART00111",
                        "channel": "web"
                    }
                },
                "POS_attributes": {
                    "description": "POS related attidional information",
                    "attributes": {
                        "POS_ref": "POS001",
                        "store_id": "STORE001"
                    }
                }
            },
            "addedFromCart": false,
            "prerelease": false,
            "disableNotification": false,
            "notifyMe" : true
        }
    ]
}

Get Wishlist Item by Item Id

Returns the wishlist item belonging to the given item Id (TWC internal item identifier)

If the item does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlist/items/{id}
Method	GET
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
path variable	id id is the TWC generated unique identifier of the wishlist item.
How to get access token	Tenant Authentication

Sample Response - 200 (OK)

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistItemRef": "WI200013716",
    "purchased": false,
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
        "productRef": "100019951",
        "selectedVariantId": "3a40289c-d56b-49f2-b0f7-d3383a36bc80",
        "selectedVariantRef": "6665"
    },
    "createdTime": "2023-05-01T02:37:22.407387Z",
    "modifiedTime": "2023-05-01T04:57:45.835957Z",
    "attributeGroups": {
        "cart_attributes": {
            "description": "cart info",
            "attributes": {
                "cart_ref": "CART00111",
                "channel": "web"
            }
        },
        "POS_attributes": {
            "description": "POS related attidional information",
            "attributes": {
                "POS_ref": "POS001",
                "store_id": "STORE001"
            }
        }
    },
    "addedFromCart": false,
    "prerelease": false,
    "disableNotification": false,
    "notifyMe" : true
}

HTTP Status Code:

- 200 OK
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Get Wishlist Item by Item Ref

Returns the wishlist item belonging to the given itemRef (retailer’s own item identifier).

Note that itemRef is the client’s unique identifier for a wishlist item associated with a single wishlist. It is NOT the productRef, which typically could be the retailer’s product SKU.

If the item does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlist/items/ref={wishlistItemRef}
Method	GET
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
path variable	wishlistItemRef is the retailer assigned unique wishlist reference identifier.
How to get access token	Tenant Authentication

Sample Response - 200 (OK)

{
    "id": "9a5aee4a-f20a-4478-ab4e-02d8bf8c2837",
    "wishlistItemRef": "WI200013716",
    "purchased": false,
    "wishlistId": "67ccc612-0f1b-4d9d-b69e-d43511c6782d",
    "product": {
        "productId": "ede20e6c-88c8-41d9-b0a5-a631871b23d2",
        "productRef": "100019951",
        "selectedVariantId": "3a40289c-d56b-49f2-b0f7-d3383a36bc80",
        "selectedVariantRef": "6665"
    },
    "createdTime": "2023-05-01T02:37:22.407387Z",
    "modifiedTime": "2023-05-01T04:57:45.835957Z",
    "attributeGroups": {
        "cart_attributes": {
            "description": "cart info",
            "attributes": {
                "cart_ref": "CART00111",
                "channel": "web"
            }
        },
        "POS_attributes": {
            "description": "POS related attidional information",
            "attributes": {
                "POS_ref": "POS001",
                "store_id": "STORE001"
            }
        }
    },
    "addedFromCart": false,
    "prerelease": false,
    "disableNotification": false,
    "notifyMe" : true
}

HTTP Status Code:

- 200 OK
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Delete Wishlist Item

Delete Wishlist Item by Id

Delete Wishlist item marks the item matching the given item ID (TWC internal platform ID) as deleted and produces an HTTP response confirming the action.

If the wishlist/item does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlist/items/{id}
Method	DELETE
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
id	This is the TWC system generated unique wishlist item identifier. e.g: 67ccc612-0f1b-4d9d-b69e-d43511c6782d. The API will remove the wishlist item for the given identifier, if it exists.
Query Parameters
purchasedAndRemoved	This Boolean parameter is used to differentiate and identify the wishlist items removed after sale conversions. This can be set manually or automated
How to get access token	Tenant Authentication

Response - 204 (Deleted)

HTTP Status Code

- 204 Deleted
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

Delete Wishlist Item by itemRef

Delete Wishlist Item by itemRef marks the item matching the given itemRef (retailer’s own identifier) as deleted and produces an HTTP response confirming the action.

Note that itemRef is the client’s unique identifier for a wishlist item associated with a single wishlist. It is NOT the productRef, which typically could be the retailer’s product SKU.

If the wishlist/item does not exist, this method returns a ResourceNotFound error.

Endpoint	/api/wishlist/items/{wishlistItemRef}/ref
Method	DELETE
Headers	Content-Type: application/json X-TWC-Tenant <tenant-key> Authorization <tenant-access-token>
wishlistItemRef	This is the TWC retailer assigned unique wishlist item identifier. e.g: WISHITEM111111. The API will remove the wishlist item for the given reference, if it exists.
Query Parameters
purchasedAndRemoved	This Boolean parameter is used to differentiate and identify the wishlist items removed after sale conversions. This can be set manually or automated

Response - 204 (Deleted)

HTTP Status Code

- 204 Deleted
- 401 Unauthorized
- 403 Forbidden 
- 404 Not Found

---

Back to Top

Back to Home