> 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/wishlist-rest-api/representations.md). # 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."
 }
}

| #### Wishlist Item 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 \.
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 \
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 | Retailer assigned unique identifier for the wishlist. Either wishlistId or wishlistRef is mandatory when creating a wishlist item. | | *wishlistItemRef* | string | Retailer assigned unique identifier for the wishlist item. | | *prerelease* | boolean | Indicates that customer is registering interest to a pre release item. Typically used to give retailers an early target list for a new product collection | | *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 | Typically used for 'notify me when an item is back in stock'. | | *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. The Wishlist automatically imports product from Shopify | | *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. The Wishlist automatically imports locations from Shopify | | *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."
 }
}

|