> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Item to Wishlist

> The Add Item to Wishlist endpoint adds a variant to an existing wishlist by creating a new `wished_item`. A wished item in a wishlist is comparable to a line item in a cart.

Each wished item references a single variant, holds the desired quantity and returns price information determined by the variant price in current currency, and desired quantity.



## OpenAPI

````yaml /api-reference/storefront.yaml post /api/v2/storefront/wishlists/{token}/add_item
openapi: 3.0.3
info:
  version: 2.0.0
  title: Storefront API
  description: >-
    Storefront API is a modern REST API based on the [JSON API
    spec](https://jsonapi.org/) which provides you with all the necessary
    endpoints to build amazing user interfaces either in JavaScript frameworks
    or native mobile libraries.


    Import to
    [Postman](https://raw.githubusercontent.com/spree/spree/main/docs/api-reference/storefront.yaml)
  contact:
    name: Vendo Connect Inc.
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  license:
    name: BSD-3-Clause
    url: https://github.com/spree/spree/blob/main/LICENSE.md
servers:
  - url: https://demo.spreecommerce.org
    description: demo
  - url: http://localhost:3000
    description: localhost
security: []
tags:
  - name: Account
  - name: Account / Address
  - name: Account / Credit Cards
  - name: Account / Orders
  - name: Cart
  - name: Cart / Line Items
  - name: Cart / Coupons
  - name: Cart / Other
  - name: Checkout
  - name: Checkout / State
  - name: Checkout / Shipments
  - name: Checkout / Payments
  - name: Checkout / Store Credit
  - name: Stripe
  - name: Adyen
  - name: Countries
  - name: Digital Downloads
  - name: Order Status
  - name: Products
  - name: Variants
  - name: Stores
  - name: Policies
  - name: Taxons
  - name: Vendors
  - name: Wishlists
  - name: Wishlists / Wished Items
paths:
  /api/v2/storefront/wishlists/{token}/add_item:
    parameters:
      - schema:
          type: string
        name: token
        in: path
        required: true
    post:
      tags:
        - Wishlists / Wished Items
      summary: Add Item to Wishlist
      description: >-
        The Add Item to Wishlist endpoint adds a variant to an existing wishlist
        by creating a new `wished_item`. A wished item in a wishlist is
        comparable to a line item in a cart.


        Each wished item references a single variant, holds the desired quantity
        and returns price information determined by the variant price in current
        currency, and desired quantity.
      operationId: add-item-to-wishlist
      parameters:
        - $ref: '#/components/parameters/Token'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                variant_id:
                  type: string
                  description: The variant ID that is to be added to the wishlist.
                quantity:
                  type: number
                  description: >-
                    Set a quantity greater than 0, or omit the quantity param if
                    your wishlist does not support quantities.
              required:
                - variant_id
            examples:
              Add a variant:
                value:
                  variant_id: '149'
                  quantity: 3
        description: >-
          Passing a quantity value is optional for those wishlist systems that
          do not support quantities. In this scenario, the returned quantity
          value will always be `1`, allowing the add-to-cart and pricing to
          reflect the single representation of the wished item accurately.


          If the wishlist system you are building allows for setting quantity,
          add the quantity attribute to the request body with an integer value
          greater than zero.
      responses:
        '200':
          $ref: '#/components/responses/WishedItem'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
        - bearerAuth: []
components:
  parameters:
    Token:
      name: token
      in: path
      required: true
      description: The token is a unique string used to identify the target resource.
      schema:
        type: string
      example: vmJtMiMozBdFtn1VkdJ8dYen
  responses:
    WishedItem:
      description: 200 Success - Returns an array of `wished_item` objects.
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/WishedItem'
              included:
                type: array
                items:
                  $ref: '#/components/schemas/WishedItemIncludes'
            required:
              - data
          examples:
            Wished Item:
              value:
                data:
                  id: '1'
                  type: wished_item
                  attributes:
                    quantity: 3
                    price: '55.99'
                    total: '167.97'
                    display_price: $55.99
                    display_total: $167.97
                  relationships:
                    variant:
                      data:
                        id: '149'
                        type: variant
            Wished Item including Variant:
              value:
                data:
                  id: '2'
                  type: wished_item
                  attributes:
                    quantity: 3
                    price: '52.99'
                    total: '158.97'
                    display_price: $52.99
                    display_total: $158.97
                  relationships:
                    variant:
                      data:
                        id: '150'
                        type: variant
                included:
                  - id: '150'
                    type: variant
                    attributes:
                      sku: JacketsandCoats_wool-blendcoat_52.99_beige_xs
                      weight: '0.0'
                      height: null
                      width: null
                      depth: null
                      is_master: false
                      options_text: 'Color: beige, Size: XS'
                      options:
                        - name: Color
                          value: beige
                          presentation: Beige
                        - name: Size
                          value: XS
                          presentation: XS
                      purchasable: true
                      in_stock: true
                      backorderable: false
                      currency: USD
                      price: '52.99'
                      display_price: $52.99
                      compare_at_price: null
                      display_compare_at_price: null
                    relationships:
                      product:
                        data:
                          id: '34'
                          type: product
                      images:
                        data: []
                      option_values:
                        data:
                          - id: '10'
                            type: option_value
                          - id: '23'
                            type: option_value
    403Forbidden:
      description: 403 Forbidden - You are not authorized to access this page.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: You are not authorized to access this page.
                default: You are not authorized to access this page.
          examples:
            403 Example:
              value:
                error: You are not authorized to access this page.
    422UnprocessableEntity:
      description: 422 Unprocessable Entity
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            422 Example:
              value:
                error: Example is invalid
                errors:
                  example:
                    - Example is invalid
  schemas:
    WishedItem:
      type: object
      x-internal: false
      properties:
        id:
          type: string
        type:
          type: string
          default: wished_item
        attributes:
          type: object
          properties:
            quantity:
              type: integer
            price:
              type: string
            total:
              type: string
            display_price:
              type: string
            display_total:
              type: string
        relationships:
          type: object
          properties:
            variant:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
      required:
        - id
        - type
        - attributes
        - relationships
    WishedItemIncludes:
      x-internal: false
      title: Wished Item Includes
      allOf:
        - $ref: '#/components/schemas/Variant'
    Error:
      x-internal: false
      title: Error
      type: object
      properties:
        error:
          type: string
    Relation:
      type: object
      nullable: true
      properties:
        id:
          type: string
        type:
          type: string
      required:
        - id
        - type
      x-internal: false
      description: ''
    Variant:
      title: Variant
      description: >-
        Variant records track the individual variants of a Product. Variants are
        of two types: master variants and normal variants.
      x-examples: {}
      type: object
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: variant
        attributes:
          type: object
          properties:
            sku:
              type: string
              example: SKU-1001
            price:
              type: string
              example: '15.99'
            currency:
              type: string
              example: USD
            display_price:
              type: string
              example: $15.99
            weight:
              type: string
              example: '10'
              nullable: true
            height:
              type: string
              example: '10'
              nullable: true
            width:
              type: string
              example: '10'
              nullable: true
            depth:
              type: string
              example: '10'
              nullable: true
            is_master:
              type: boolean
              description: Indicates if Variant is the master Variant
            options_text:
              type: string
              example: 'Size: small, Color: red'
            options:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
                  presentation:
                    type: string
            purchasable:
              type: boolean
              description: Indicates if Variant is in stock or backorderable
            in_stock:
              type: boolean
              description: Indicates if Variant is in stock
            backorderable:
              type: boolean
        relationships:
          type: object
          properties:
            product:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            images:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            option_values:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
      required:
        - id
        - type
        - attributes
        - relationships
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        User token to authorize Cart and Checkout requests.

        It is required to associate Cart with the User.

````