> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/getting-started/readme.md).

# Getting Started with The Wishlist

## What is The Wishlist

The Wishlist is a microservices-based, API-enabled engine that empowers retailers to understand and manage lists of products that their customers want to purchase ("wishlists").

Retailers integrate The Wishlist with their website, and optionally into their physical retail stores, so that customers can easily save items they are interested in, and so that they can market more effectively to their customers.

**Automated notifications** can be configured and sent to customers when products are low in stock, back in stock, on sale, or added to a wishlist. Reminders can also be regularly sent to customers.

**On-demand notifications** are retailer-triggered alerts that can be configured to notify customers about items that are coming soon, or that have been restocked.

A dashboard and set of reports available through a reporting console help retailers understand customer demand, popular products and wishlist conversions.

The Wishlist also integrates to **Point Of Sale (POS)** in-store. This makes it an ideal way for retailers to bridge online and offline services.

The Wishlist integrates with websites, store POS, existing marketing and ERP platforms via APIs and in the case of Shopify, a Shopify App.

The core of the The WIshlist delivers world-class features to manage one or more wishlists for a customer (The Wishlist provides the **master record** for wishlist) and associated customers, products, inventory, and prices.

The Wishlist also manages store and staff details (where applicable) from retailers so that activities can be properly attributed and reported. In the context of a store deployment, there are additional features such as list management, SMS and MMS messaging, recommendations and clienteling.

## Basic concepts

* The Wishlist provides world-class wishlist capabilities for ecommerce platforms and in-store point of sale and a clienteling platform for multi-channel retailers.
* Developers integrate The Wishlist into their applications using The Wishlist's **REST and JavaScript APIs** In the case of Shopify, things are made simpler with a Shopify App.
* Typically The Wishlist platform operates with real-time integration between ecommerce, marketing, and Point of Sale.
* To achieve the best outcome, you will also integrate in real-time or near real-time integration with customer, pricing and inventory systems. We integrate with these systems so that real-time **notifications** can be sent to retailers' customers when an item on their wishlist is out of stock, back in stock, or on sale.
* In order to track wishlist performance and send notifiations to customers, we also require **product and sales data**. With Shopify, this integration can be automated via Shopify Webhooks. For other platforms, we typically integrate via batch processing/synchronisation.
* For retailers that want to track performance of stores and staff, we will also require integration with these data types - typically via batch integration, although these can also be manually maintainted in our admin console.

In The Wishlist, customers are identified by, at minimum, their email address (this **must be unique**, with no other account attached to the email address). In addition **mobile phone** must be unique.

## Platform components

In addition to wishlist management , we offer the following modules:

* **Store Owner console** allows retailers to customise system configurations and analyse system performance
* **Shopify app** is a turnkey solution for Shopify merchants. Provides both frontend customisation and backend integration to The Wishlist
* **Reports console** is a standalone UI for accessing the Wishlist dashboard and reports
* **Clienteling (POS App)** provides an optional React-based front-end allowing retailers to offer Clietenling features in-store including wishlist, preference management and customer messaging
* **Shopify POS App** An app built for Shopify POS that provides in-store Wishlist
* **Marketing integrations** allow third-party platforms such as Emarsys, Klaviyo, Braze, Yotpo and DotDigital to be used as the platform for Wishlist notifications.

## Notifications

The Wishlist automatically sends marketing communications to customers based on events and the settings retailers create in the **Store Owner Console**.

For example, you can notify customers based on:

* Regular schedules (eg reminder emails)
* Stock levels (eg when an item is low in stock or back in stock)
* Price changes (eg when an item is on sale)
* Add to wishlist
* Add to wishlist in-store
* When an item comes back into stock

Key considerations for notifications:

* **Customer must be opted-in to receive a notification**
* **A product (and image) must exist for notifications to be triggered.** A customer can add products to their wishlist even if the product isn't available in the product catalogue. However, the product must exist with attributes including image, price and description in order for notifications to trigger, as these attributes have to be sent to the marketing platform with the notification payload.
* For **stock-based notifications**, inventory must be loaded and synchronised into The Wishlist.
* For **Price-based notifications**, pricing must be loaded and synchronised into The Wishlist.
* For **Emarsys** integrations, The Wishlist sends all wishlist changes to Emarsys, with wishlist notifications managed in and by Emarsys.
* With **Klaviyo**, notifications are managed in The Wishlist. Retailers create **Flows** in Klaviyo, and The Wishlist creates metrics that are used in the Flows. The Wishlist then sends events and payloads to Klaviyo, triggering the appropriate Flow.
* For **DotDigital**, notifications are managed in The Wishlist. Retailers register the DotDigital template associated with the notification in the TWC Store Owner console. When a notification is triggered, The Wishlist sends the payload, along with the appropriate template iD, to DotDigital.

There is also a special type of Wishlist notifications called **Subscriptions**

### Subscriptions (Notify Me & Register Interest)

In addition to our automated Wishlist notifications (which are based on stock levels, price, events or time), The Wishlist Company also offers a Subscriptions feature. **These notifications require use of our Javascript widget(s)**

Subscriptions give the shopper the ability to quickly register their interest in a product with just an email address. The wishlist provides two types of subscriptions: Notify me and Register Interest.

**Notify me (Back in stock)**: This subscription is used customers to receive a Back in stock alert when a currently out of stock item returns into the warehouse/store.

This alert is typically used as follows: When an item goes out of stock, retailers change the item’s ‘Add to cart’ button to a ‘Notify me when back in stock’ button, giving customers the option to be alerted when a product is back in stock. This alert is automatic, and will send a list of all customers subscribed to your marketing system when the item is back in stock (subject to the retailer defined threshold). You can also download the current list of subscribed customers at any time.

**Register interest (Coming soon)**: when a retailer wants to gauge interest in an upcoming product, they can offer a ‘Register your interest’ button. An example of this alert is if you want to offer VIP customers early access to a new product, and create a hidden page on your website exclusively for them where they can subscribe to be given more details when the stock is about to arrive. This option has no automatic alert, but you can either download a list of subscribed customers, or upload the list to your marketing platform.

Access to the Notify me and Register interest subscriptions is available to developers via the **customerInterest API**, with reporting available in the Store Console.

The Wishlist Company also offers a **customerInterest Javascript widget** that makes it easy to add subscription alert functionality to a button on your website. This widget requires an email to be provided at minimum, but also allows you to capture mobile phone, first name and last name if you want to request more information from your shoppers. We also include a checkbox that if checked will also opt the customer in for general marketing communications. The widget has been designed to automatically pull the correct variant in for Shopify, but can be easily adapted for other platforms. For Shopify, when using it on the product details page, the variant number should pass automatically from the current environment variables.

Here are some important considerations about our subscriptions feature:

* A customer request for a Notify Me (e.g. back-in-stock) alert assumes that the alert is a transactional communication, not a marketing communication, and we will by default ignore opt-out status for that customer. The customer can optionally request a full opt-in at the same time using the same API ("Subscribe"), in which case TWC will immediately forward the customer's details to your marketing platform.
* If the customer’s email already exists in The Wishlist, the subscription will be tied to that customer. If they don’t exist, they will be created, and if they later sign up to your database, The Wishlist will match them to the existing record. (Note, we also validate mobile phone is unique, and will reject any records that include a mobile phone if that mobile phone number is linked to a different email address in our database)
* A Notify Me alert for a given product will only fire once. If required, the retailer can reset the alert.
* Notify me when back in stock differs from the standard wishlist back-in-stock notification in the following ways:
* The item does not have to be on a wishlist
* The customer doesn’t have to provide a full registration. They can simply provide an email address.
* The wishlist notification will continue to fire whenever the product becomes available after being unavailable. The subscription alert fires only once
* Items are subscribed to at the variant level (i.e. colour/size)
* Items subscribed to via Notify Me and Register Interest are not returned in our standard Wishlist query APIs. If you wish to return these items (for example, to display them on the customer’s my-account page), you must use the customerInterest API.
* You can remove items from an individual customer using the customerInterest API (we recommend after a customer asks to be notified, that retailers change the ‘Notify me when back in stock’ button to indicate that the customer has subscribed. If they subsequently want to cancel their subscription to that alert, then use the customerInterest API to remove them.
* You can view the list of subscribed customers in the Store Console Reports. You can also download to your local drive, upload to your marketing platform, and reset a particular item’s notification status from here.
* The subscriptions must be enabled in the notification section of the Store Console. This initiates configuration in the marketing platform e.g. in Klaviyo, this will set up two metrics: TWC Notify Me - Back in Stock, and TWC Coming Soon - Register Interest’.
* Note, we also recommend that you set up treatments in your marketing system (e.g. in Klaviyo, ‘flows’) that do not send the notification if the customer has received an email in the prior 15 minutes.
* For back in stock alerts, a threshold must be set. Stock must be above this level before the automatic alert will trigger. You can also set a time delay (we recommend 5-15 minutes).

## Conversion tracking

TWC identifies and reports on sales conversions for products that have been wishlisted, subscribed to, or included in text messsaging to clients.

The conversion types we track automatically are:

* Wishlist item: If an item that has been on a customer wishlist is later purchased
* Subscription: If an item that was previously subscribed to (notify me or register interest), is later purchased
* Quote: If a quote was later converted into an order
* Message: If an item is included in a text message to a client from our Wishlist InStore solution, is later purchased.

Please note the following:

* Conversions are attributed to the location and staff identifier (if any) for where the item was originally added to the wishlist or messaged to the customer.
* One item may have more than one conversion type (e.g. could be both on a wishlist, and also messaged)
* In order to attribute conversions correctly, location information should be attached to wishlists and wishlist items. In addition, if you are integrating with a 3rd party point of sale, you should also include your staff identifier in the wishlist and wishlist item transactions. In TWC's Wishlist InStore module this occurs automatically, and in addition we track and attribute products that are included in SMS/MMS messages to clients. We also do this automatically for Triquestra Infinity POS, Shopify POS and NewStore POS.
* We track conversion at a product level, not a variant level. This means that if a customer places an item size 3 on their wishlist, but later purchases a size 4, this will still count as a conversion.
* There is no timelimit on the conversion period - even on deleted items.
* Quote conversions occur at the header level, not the item level.
* You can track conversion summaries and details in the Wishlist Store Console.

## Importing & Exporting data

TWC provides out of the box integration to many third party platforms, including Shopify, Triquestra Infinity, AP21, Feedonomics, Klaviyo, Emarsys, Sendgrid, Tallbob and DotDigital.

In addition, we also enable you to integrate integrate data from your systems via our APIs. The data types that may be integrated are:

* Product & variant data, including pricing and inventory. This data is used for notifications and reporting.
* Location & Staff data
* Customer data (required in real-time, or near-real-time)

If you prefer, you can upload data to our AWS S3 bucket and we can import your data for you provided it conforms to our requirements.

Please contact us for more details on setting up your data integration, and review the API documentation available on these pages.

### Exporting data

The Wishlist Company also provides APIs that you can use to exporting wishlist and quote data to your systems. These APIs have an 'updated-since' parameter to allow you to get all data changed since the provided date. Please review our API documentation and contact us for more details

## Data types

| Data type      | Use                                                                                                            | Special considerations                                                                                                                     |
| -------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Customer       | Wishlists must belong to a customer. A customer must exist before a wishlist can be created                    | Email is unique, and required                                                                                                              |
| Wishlist       | A customer can have one or more wishlists.                                                                     | The Wishlist is assumed to be the master data manager of Wishlists                                                                         |
| Wishlist Items | Each wishlist can have one or more wishlist items                                                              |                                                                                                                                            |
| Products       | Marketing and notifications                                                                                    | A product does not need to exist before being added to a wishlist. However, it must exist before it can be sent as a customer notification |
| Pricing        | Marketing and notifications                                                                                    | Required for pricing notifications                                                                                                         |
| Orders (sales) | Determining which wishlist items have converted to sales                                                       | Required for conversion and sales reporting                                                                                                |
| Quotes         | A special type of wishlist allowing a business to send quote reminders and track quotes that convert to orders | Optional module. Behaves a little differently to wishlists, and has its own set of notifications                                           |
| Inventory      | Marketing and notificatins                                                                                     | Required for stock notifications                                                                                                           |
| Staff          | Ability to attribute sales and conversions to staff                                                            | Required for staff attribution and optional clienteling module. Staff must have a unique ID, and are NOT assigned to a single store        |
| Stores         | Ability to attribute sales and conversions to a store                                                          | Required for staff attribution and optional clienteling module. Stores (locations) must have a unique identifier                           |

## Using the REST APIs

***Note: If you plan to use our Rest APIs directly, then you will require credentials to be provided by us. Your credentials must be managed securely. Do not store your wishlist credentials in your frontend. Either extend the backend of your e-commerce system to make the API calls to The Wishlist and send the information to the frontend from there, or create an integration latyer that communicates with both your ecommerce backend and The Wishlsit, and make the fronend use the API layer.***

### Authentication

The wishlist uses bearer authentication. Tokens expire after **5 minutes**. For tenant details, contact The Wishlist team.

### Rest API endpoints

Detailed documentation regarding The Wishlist Rest APIs is located on this site

### Javascript API endpoints

Detailed documentation regarding The Wishlist Javascript APIs is located here: [Javascript](https://github.com/The-Wishlist-Co/twc-api-specs/blob/main/docs/getting-started/docs/Javascript.md)

### Notes and special use cases

**Add items at the variant level:** We highly recommend adding items at the variant (size/colour) level, not the parent product level. One customer-centric reason for this is that customers may be interested in certain sizes or colours, and if they receive a notification regarding stock availability but then find out that their particular size/color is not available in their particular size or color, they can quickly become dissatisfied with the experience.

**Identifiers:** All platform entities have a unique TWC internal identifier. This is typically identified by the appendix 'id' (eg `customerId`), and an optional unique identifier specified by the customer, typically identified by the appendix 'Ref', (eg `customerRef`). For customers, the email must be unique and is a required field. Mobile is also a unique field, and items will be rejected if they contain a field that is duplicated in the database/

**Deleting items:** When using the delete APIs, The Wishlist typically marks items for deletion without deleting them from the database. This is because the items are often needed for historical reporting.

**Deleting wishlist items:** When using the Rest APIs, a delete item API will mark an item as deleted, and no longer return the item in a list of wishlist items, but it will not actually delete the item as it is still required for The Wishlist internal reporting purposes. The Wishlist doesn't automatically delete an item after it's been purchased by a customer. If you don't want to leave the item in a wishlist after it is purchased, your developer must specifically mark it as deleted it using the delete item API.

**Purchase and delete option:** The Wishlist offers an optional setting for retailers called 'Purchase and Delete'. If this is set TRUE, then Shopify will automatically delete an item from the customer's wishlist when it is purchased. If it is false, the item will remain in the customer's wishlist even if it is purchased. Developers using the Rest APIs can also leverage this flag to build similar behaviour in their websites.

**Added from cart:** For abandoned carts, you have the option to add all items to a wishlist. The Wishlist provides a flag at wishlist item level `addedFromCart` for developers to record which items have been automatically added to The Wishlist from the abandoned cart.

**Please refer to our** [**Development Best Practices**](https://github.com/The-Wishlist-Co/twc-api-specs/blob/main/docs/getting-started/Best-Practices-for-developers/README.md) **for more details about how to best integrate with TWC.**