Add items to wishlist

Add items to a wishlist. Send either product_ids OR variant_group_ids, not both.\n- product_ids: save the whole product (variant_group_id will be null on the item).\n- variant_group_ids: save a specific variant group; product_id is derived from the group.

POST/api/v1/{app_id}/wishlists/{id}/items

API: Auth
OpenAPI: auth-api
Updated: Apr 26, 2026

auth-api:POST:/api/v1/{app_id}/wishlists/{id}/items

Add items to a wishlist. Send either product_ids OR variant_group_ids, not both.

product_ids: save the whole product (variant_group_id will be null on the item).
variant_group_ids: save a specific variant group; product_id is derived from the group.

API ownership

API family: Auth API
Best for: Customer identity, session, token, cart, and wishlist flows.
Do not use from: Merchant admin data syncs or public catalog rendering.
Guide route: /apis/auth/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

Method: POST
Path: /api/v1/\{app_id\}/wishlists/\{id\}/items
Summary: Add items to wishlist
Description: Add items to a wishlist. Send either product_ids OR variant_group_ids, not both.
product_ids: save the whole product (variant_group_id will be null on the item).
variant_group_ids: save a specific variant group; product_id is derived from the group.
OpenAPI contract: auth-api
Operation ID: Not documented in the OpenAPI contract.

Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID.

Parameters2 parameters

Name	In	Required	Type	Description
app_id	path	Yes	string	UUID of the app
id	path	Yes	string	UUID of the wishlist

Request bodyDocumented body

Required: Yes
Description: Items to add
Content: application/json (object)

Add Wishlist Items Request

Property	Type	Required	Details
`product_ids`	string[]	No	Product IDs for product-level wishlist items. Mutually exclusive with variant_group_ids.
`variant_group_ids`	string[]	No	Variant group IDs for group-scoped wishlist items. Mutually exclusive with product_ids. Product ID is derived from each group.

Generated example (synthetic):

{
  "product_ids": [
    "string"
  ],
  "variant_group_ids": [
    "string"
  ]
}

Responses5 statuses

Status	Description	Content
200	Items added successfully	application/json (object)
400	Invalid request	application/json (object)
401	Unauthorized	application/json (object)
404	Wishlist not found	application/json (object)
500	Internal server error	application/json (object)

200 - object

Message

Property	Type	Required	Details
`message`	string	No	-

Generated example (synthetic):

{
  "message": "string"
}

400 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

401 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

404 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

500 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

API family: Auth API
Method: POST
Path: /api/v1/\{app_id\}/wishlists/\{id\}/items
Operation ID: Not documented in the OpenAPI contract.
OpenAPI tag: Wishlist
OpenAPI summary: Add items to wishlist