--- title: "Add an item" method: POST path: "/v1/wishlists/{wishlistId}/items" tags: ["wishlists"] --- # Add an item `POST /v1/wishlists/{wishlistId}/items` Through this endpoint, you are able to add items to a customer's wishlist. Some important points should be taken into consideration: * Items might be added both using its product ID or the variant ID. * There is a limit regarding the maximum amount of items that might be added to the wishlist. The current limit is **200 items**. ## Path parameters - `wishlistId` string, required ## Query parameters - `campaignKey` string - `pricePromotionKey` string - `displayHighestPpkPrice` boolean - `forcePPKSaleCategories` boolean - `with` string[] ## Request body - CreateWishlistBody — Either variantId or productId must be provided. - `variantId` integer, nullable — Variant ID to add to the wishlist. - `productId` integer, nullable — Product ID to add to the wishlist. When provided, the first found in-stock variant of the product will be added. - `customData` object - `quantity` integer, nullable — The quantity for the variant. ## Response `200` request successful - Wishlist - `key` string, required - `items` WishlistItem[], required - `key` string, required - `packageId` integer, required - `quantity` integer, required - `status` 'available' | 'unavailable', required - `product` Product - `id` integer, required - `advancedAttributes` object - `attributes` object - `baseCategories` BaseCategory[] - `categoryId` integer, required — Unique identifier of the category - `categoryName` string, required — Name of the category - `categoryParentId` integer, required — Parent ID of the category - `categoryPath` string, required — Category path as text - `categories` array[] - ProductCategory[] - `categoryId` integer - `categoryHidden` boolean - `categoryName` string - `categoryProperties` object - `is_inheritable` integer - `name` string - `value` string - `shopLevelCustomData` object - `appCatName` object - `appCatLocalizedConfig` object - `countryLevelCustomData` object - `appCatCountryName` string - `appCatCountryScore` number - `appCatCountryBubbleUp` boolean - `appCatCountrySampleName` string - `appCatCountrySampleConfig` object - `appCatCountryLocalizedConfig` object - `categoryUrl` string - `categorySlug` string - `definingAttributes` DefiningAttribute - `id` integer, required - `label` string, required - `images` Image[], required - `attributes` object - `hash` string - `customData` ResponseCustomData, required - `isActive` boolean, required — Identifies whether a product is active or not - `isNew` boolean, required — Identifies whether a product is new or not - `isSoldOut` boolean, required — Identifies if a product is still available to sell - `masterKey` string, required — Identifies the master product which this product belongs - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `priceRange` PriceRange - `max` Price, required - `appliedReductions` AppliedReduction[], required - `amount` AppliedReductionAmount, required - … - `category` 'sale' | 'campaign' | 'promotion', required - `type` string, required - `currencyCode` string, required — The currency of the price. - `reference` object - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement. - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value - `withoutTax` integer — Reference price excluding the taxes. - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request). - `tax` Tax, required - `vat` Vat - … - `withoutTax` integer, required - `withTax` integer, required - `recommendedRetailPrice` integer, required - `min` Price, required - `appliedReductions` AppliedReduction[], required - `amount` AppliedReductionAmount, required - … - `category` 'sale' | 'campaign' | 'promotion', required - `type` string, required - `currencyCode` string, required — The currency of the price. - `reference` object - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement. - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value - `withoutTax` integer — Reference price excluding the taxes. - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request). - `tax` Tax, required - `vat` Vat - … - `withoutTax` integer, required - `withTax` integer, required - `recommendedRetailPrice` integer, required - `reductionRange` ReductionRange - `max` Price - `appliedReductions` AppliedReduction[], required - `amount` AppliedReductionAmount, required - … - `category` 'sale' | 'campaign' | 'promotion', required - `type` string, required - `currencyCode` string, required — The currency of the price. - `reference` object - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement. - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value - `withoutTax` integer — Reference price excluding the taxes. - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request). - `tax` Tax, required - `vat` Vat - … - `withoutTax` integer, required - `withTax` integer, required - `recommendedRetailPrice` integer, required - `min` Price - `appliedReductions` AppliedReduction[], required - `amount` AppliedReductionAmount, required - … - `category` 'sale' | 'campaign' | 'promotion', required - `type` string, required - `currencyCode` string, required — The currency of the price. - `reference` object - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement. - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value - `withoutTax` integer — Reference price excluding the taxes. - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request). - `tax` Tax, required - `vat` Vat - … - `withoutTax` integer, required - `withTax` integer, required - `recommendedRetailPrice` integer, required - `lowestPriorPrice` LowestPriorPrice — Information about the lowest price in the past 30 days. - `withTax` integer, nullable, required — The lowest price including tax. - `relativeDifferenceToPrice` number, float, nullable, required — The relative difference from the lowest prior price to the current price. If the value is positive, it means that the current price is higher than the lowest prior price. If the value is negative, it means that the current price is lower than the lowest prior price. - `referenceKey` string, required - `searchCategoryIds` integer[] - `siblings` Product[] — list of Products - `variants` Variant[] - `id` integer, required - `advancedAttributes` object - `appliedPricePromotionKey` string - `attributes` object - `lowestPriorPrice` LowestPriorPrice — Information about the lowest price in the past 30 days. - `withTax` integer, nullable, required — The lowest price including tax. - `relativeDifferenceToPrice` number, float, nullable, required — The relative difference from the lowest prior price to the current price. If the value is positive, it means that the current price is higher than the lowest prior price. If the value is negative, it means that the current price is lower than the lowest prior price. - `price` Price, required - `appliedReductions` AppliedReduction[], required - `amount` AppliedReductionAmount, required - … - `category` 'sale' | 'campaign' | 'promotion', required - `type` string, required - `currencyCode` string, required — The currency of the price. - `reference` object - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement. - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value - `withoutTax` integer — Reference price excluding the taxes. - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request). - `tax` Tax, required - `vat` Vat - … - `withoutTax` integer, required - `withTax` integer, required - `recommendedRetailPrice` integer, required - `productId` integer, required - `referenceKey` string, required - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `stock` Stock, required - `supplierId` integer, required - `warehouseId` integer, nullable, required - `quantity` integer, required - `isSellableWithoutStock` boolean, required - `expectedAvailabilityAt` string, nullable, required - `customData` object, required - `merchant` Merchant - `id` integer, required - `key` string, required - `name` string, required - `legal` object - `legaName` string - `parentCompanyLegalName` string - `streetWithNumber` string - `zip` string - `city` string - `country` string - `telephone` string - `email` string - `registryCourtCity` string - `registerNumber` string - `parentCompanyRegistryCourtCity` string - `parentCompanyRegisterNumber` string - `managingDirectors` string - `representative` string - `shippingMerchantName` string - `registryCourtType` string - `parentCompanyRegistryCourtType` string - `vatId` string - `createdAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `updatedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `createdAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `updatedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `indexedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `variant` Variant - `id` integer, required - `advancedAttributes` object - `appliedPricePromotionKey` string - `attributes` object - `lowestPriorPrice` LowestPriorPrice — Information about the lowest price in the past 30 days. - `withTax` integer, nullable, required — The lowest price including tax. - `relativeDifferenceToPrice` number, float, nullable, required — The relative difference from the lowest prior price to the current price. If the value is positive, it means that the current price is higher than the lowest prior price. If the value is negative, it means that the current price is lower than the lowest prior price. - `price` Price, required - `appliedReductions` AppliedReduction[], required - `amount` AppliedReductionAmount, required - `absoluteWithTax` integer - `relative` number - `category` 'sale' | 'campaign' | 'promotion', required - `type` string, required - `currencyCode` string, required — The currency of the price. - `reference` object - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement. - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value - `withoutTax` integer — Reference price excluding the taxes. - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request). - `tax` Tax, required - `vat` Vat - `amount` number - `rate` number - `withoutTax` integer, required - `withTax` integer, required - `recommendedRetailPrice` integer, required - `productId` integer, required - `referenceKey` string, required - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `stock` Stock, required - `supplierId` integer, required - `warehouseId` integer, nullable, required - `quantity` integer, required - `isSellableWithoutStock` boolean, required - `expectedAvailabilityAt` string, nullable, required - `customData` object, required - `merchant` Merchant - `id` integer, required - `key` string, required - `name` string, required - `legal` object - `legaName` string - `parentCompanyLegalName` string - `streetWithNumber` string - `zip` string - `city` string - `country` string - `telephone` string - `email` string - `registryCourtCity` string - `registerNumber` string - `parentCompanyRegistryCourtCity` string - `parentCompanyRegisterNumber` string - `managingDirectors` string - `representative` string - `shippingMerchantName` string - `registryCourtType` string - `parentCompanyRegistryCourtType` string - `vatId` string - `createdAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `updatedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `productId` integer, required - `masterKey` string - `variantId` integer - `customData` object, required ## Other responses - `400` — only one parameter must be set (variantId or productId) / either variantId or productId must be set - `401` — Authentication information is missing or invalid - `404` — The specified resource was not found - `409` — conflict - wishlist item for given variant already exists - `412` — product currently unavailable / no variant for product id found - `413` — wishlist exceeds maximum items size limitation ## Changes - **2026-07-17** `8cfa924ae703` — 12 breaking, 39 warning, 133 info - the response property `items/items/product/attributes/additionalProperties/values` became nullable for the status `200` - the response property `items/items/product/images/items/attributes/additionalProperties/values` became nullable for the status `200` - the response property `items/items/product/lowestPriorPrice/relativeDifferenceToPrice` became nullable for the status `200` - the response property `items/items/product/lowestPriorPrice/withTax` became nullable for the status `200` - …180 more - **2023-08-06** `302b7c443b51` — 151 breaking, 8 warning, 42 info - the request property `productId` became not nullable - the request property `quantity` became not nullable - the request property `variantId` became not nullable - the response property `items/items/product/attributes/additionalProperties/id` became nullable for the status `200` - …197 more [Change history](https://skmtc.dev/scayle/apis/storefront-api-documentation/changes/v1/wishlists/:wishlistId/items/post.md) --- [API](https://skmtc.dev/scayle/apis/storefront-api-documentation.md) · [All operations](https://skmtc.dev/scayle/apis/storefront-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scayle/storefront-api-documentation/revisions/8cfa924ae703/schema)