Managing Wishlists
  • 19 Mar 2020
  • 5 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Managing Wishlists

  • Print
  • Share
  • Dark
    Light

The Wishlists API provides REST access to managing wishlists of a customer. With the help of the endpoints provided by the API, you can create, list and delete wishlists, as well as manage the items inside them.

In your development, these resources can help you to enable complete wishlist functionality for your customers.

Authentication
Since wishlists are available for registered users only, the endpoints provided by the API cannot be accessed anonymously. For this reason, you always need to pass a user's authentication token in your REST requests. For details on how to authenticate a user and retrieve the token, see Authentication and Authorization.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Wishlist API Feature Integration.

Creating a Wishlist

To create a wishlist for a registered user, you need to send a POST request to the following endpoint:

/wishlists

Sample request: POST http://mysprykershop.com/wishlists
Attributes:

  • name - sets a name for the new wishlist.

Sample request body

{
		"data":{
			"type": "wishlists",
			"attributes":{
				"name":"{{my_name}}"
			}
		}
	}

Sample Response:

Field* Type Description
name String Name of the wishlist
numberOfItems Integer Number of items in the wishlist
createdAt String Creation date of the wishlist
updatedAt String Date of the last update

*The fields mentioned are all attributes in the response. Type and ID are not mentioned.

Sample response

{
		"data": {
			"type": "wishlists",
			"id": "09264b7f-1894-58ed-81f4-d52d683e910a",
			"attributes": {
				"name": "Name of the wishlist",
				"numberOfItems": 0,
				"createdAt": "2018-08-17 10:04:35.311557",
				"updatedAt": "2018-08-17 10:04:35.311557"
			},
			"links": {
				"self": "http://mysprykershop.com/wishlists/09264b7f-1894-58ed-81f4-d52d683e910a"
			}
		}
	}

The response contains a unique identifier, contained in the id attribute, and a self link that can be used to access the wishlist later.

Possible errors

Code Reason
202 A wishlist with the same name already exists.
203 Cannot create a wishlist.

Accessing Wishlists of User

To access all wishlists of a user, send a GET request to the following endpoint:

/wishlists

Sample request: GET http://mysprykershop.com/wishlists

Sample Response:

Field* Type Description
name String Name of the wishlist.
numberOfItems Integer Number of items in the wishlist.
createdAt String Date of the creation of the wishlist.
updatedAt String Date of the last update.

*The fields mentioned are all attributes in the response. Type and ID are not mentioned.

The endpoint will respond with a RestWishlistsResponse. The following response is returned when a user doesn't have any wishlists:

Sample response

{
		"data": [],
		"links": {
			"self": "http://mysprykershop.com/wishlists"
		}
	}

If there are any wishlists already created for a user, they will be returned in the data attribute of the response.

Sample response

{
		"data": {
  
 
	{
		"data": [
			{
				"type": "wishlists",
				"id": "1623f465-e4f6-5e45-8dc5-987b923f8af4",
				"attributes": {
					"name": "My Wishlist Name",
					"numberOfItems": 0,
					"createdAt": "2018-12-16 17:24:12.601033",
					"updatedAt": "2018-12-16 17:24:12.601033"
				},
				"links": {
					"self": "http://mysprykershop.com/wishlists/1623f465-e4f6-5e45-8dc5-987b923f8af4"
				}
			}
		],
		"links": {
			"self": "http://mysprykershop.com/wishlists"
		}
	}

Modifying Wishlists

To modify a user's wishlist, send a PATCH request to the following endpoint:

/wishlists

Sample request: PATCH http://mysprykershop.com/wishlists

Sample Request Body
The following sample changes the name of a wishlist.

Sample response

{
		"data": {
			"type": "wishlists",
			"id": "uuid",
			"attributes": {
				"name": "New Name"
			}
		}
	}

Sample Response:

Field* Type Description
name String Name of the wishlist
numberOfItems Integer Number of items in the wishlist
createdAt String Creation date of the wishlist
updatedAt String Date of the last update

*The fields mentioned are all attributes in the response. Type and ID are not mentioned.

In case of a successful update, the endpoint will also respond with a RestWishlistsResponse, where the wishlist name will be updated.

Sample response

Possible errors

Code Reason
201 Cannot find the wishlist.
202 A wishlist with the same name already exists.
204 Cannot update the wishlist.

Deleting Wishlists

To delete a wishlist, send a DELETE request:

/wishlists/{{wishlist_id}}

Sample request: DELETE http://mysprykershop.com/wishlists/09264b7f-1894-58ed-81f4-d52d683e910a

where 09264b7f-1894-58ed-81f4-d52d683e910a is the ID of the wishlist you want to remove.

Response:
If the wishlist was deleted successfully, the endpoint would respond with a 204 No Content status code.

Possible errors

Code Reason
201 Cannot find the wishlist.
205 Cannot remove the wishlist.

Getting Wishlists

The Wishlist API allows you not only to manage wishlists, but also to manage items inside them. Each wishlist item is referenced by the SKU of the respective product.

To get all items in a wishlist, send a request to the following endpoint:

/wishlists/{{wishlist_id}}

Sample request: GET http://mysprykershop.com/wishlists/09264b7f-1894-58ed-81f4-d52d683e910a

where 09264b7f-1894-58ed-81f4-d52d683e910a is the ID of the wishlist you want to retrieve.

Sample Response:

Field* Type Description
name String Name of the wishlist
numberOfItems Integer Number of items in the wishlist
createdAt String Сreation date of the wishlist
updatedAt String Date of the last update

*The fields mentioned are all attributes in the response. Type and ID are not mentioned.

If the specified wishlist exists, the endpoint will respond with a RestWishlistsResponse that contains all information on the wishlist, including information on all products that have been put there.

Sample response

{
		"data": {
			"type": "wishlists",
			"id": "63bf7566-4596-50ce-84c4-cc7260a23c16",
			"attributes": {
				"name": "mylist1",
				"numberOfItems": 1,
				"createdAt": "2018-08-22 12:31:37.924541",
				"updatedAt": "2018-08-22 12:31:37.924541"
			},
			"links": {
				"self": "http://mysprykershop.com/wishlists/63bf7566-4596-50ce-84c4-cc7260a23c16"
			}
		}
	}

Possible errors

Code Reason
201 Cannot find the wishlist.

To add an item to a wishlist, send a POST request to the following endpoint:
/wishlists/{{wishlist_id}}/wishlist-items
Sample request: POST http://mysprykershop.com/wishlists/09264b7f-1894-58ed-81f4-d52d683e910a/wishlist-items
where 09264b7f-1894-58ed-81f4-d52d683e910a is the ID of the wishlist to which you want to add an item.

Attributes:

  • sku - specifies the SKU of the product you want to add to the wishlist.

Sample request body

{
		"data": {
			"type": "wishlist-items",
			"attributes": {
				"sku": "064_18404924"
			}
		}
	}

Sample Response:

Field* Type Description
sku String Concrete product SKU.

*The fields mentioned are all attributes in the response. Type and ID are not mentioned.

The endpoint will respond with a RestWishlistItemResponse that contains information on the new wishlist item.

Sample response

{
		"data": {
			"type": "wishlist-items",
			"id": "064_18404924",
			"attributes": {
				"sku": "064_18404924"
			},
			"links": {
				"self": "http://mysprykershop.com/wishlists/c917e65b-e8c3-5c8b-bec6-892529c64b30/wishlist-items/064_18404924"
			}
		}
	}

Possible errors

Code Reason
201 Cannot find the wishlist.
206 Cannot add an item to the wishlist.

To delete an item, send a DELETE request:
/wishlists/{{wishlist_id}}/wishlist-items/{{item_sku}}

Sample request: DELETE http://mysprykershop.com/wishlists/09264b7f-1894-58ed-81f4-d52d683e910a/wishlist-items/064_18404924

where: 09264b7f-1894-58ed-81f4-d52d683e910a - the ID of the wishlist where you want to delete an item;
064_18404924 - SKU of the item you want to remove.

Response:
If the item was removed successfully, the endpoint will respond with a 204 No Content status code.

Possible errors:

Code Reason
201 Cannot find the wishlist.
207 Cannot remove the item.
208 An item with the provided SKU does not exist in the wishlist.
Was This Article Helpful?