BigCommerce Wishlist is a feature that allows customers to save products they are interested in to a personalized list for future reference. This enables them to easily keep track of items they like without having to immediately purchase them. Customers can create multiple wishlists, organize products by category, and share their lists with friends and family.
openapi: 3.0.1
info:
title: BigCommerce Wishlist
description: >-
Create and manage customer wishlists and wishlist items.
## Additional Information
* [Wishlists (Help
Center)](https://support.bigcommerce.com/s/article/Wishlists)
version: ''
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Wishlists
- name: Wishlists Items
paths:
/wishlists:
get:
tags:
- Wishlists
summary: BigCommerce Get All Wishlists
description: >-
Returns a list of wishlists. Optional filter parameters can be passed
in.
operationId: getWishlists
parameters:
- name: customer_id
in: query
description: All wishlists relating to the customer.
schema:
type: integer
format: int32
- name: page
in: query
description: >-
The page number of results per page. 1 is the default and starts
from record 0.
schema:
type: integer
format: int32
- name: limit
in: query
description: >-
The numbers of items to return per page. Default is 50 and maximum
is 250.
schema:
type: integer
format: int32
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/wishlist_Full'
meta:
$ref: '#/components/schemas/metaCollection'
example:
data:
- id: 1
customer_id: 4
name: My Wish List
is_public: false
token: 02d55481-13eb-4d1e-9d79-9062b518570d
items: []
- id: 2
customer_id: 11
name: Christmas
is_public: false
token: 02d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 1
product_id: 167
- id: 2
product_id: 174
- id: 3
product_id: 184
- id: 3
customer_id: 20
name: Birthday
is_public: false
token: 02d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 4
product_id: 184
- id: 5
product_id: 183
- id: 4
customer_id: 20
name: Christmas
is_public: false
token: 02d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 6
product_id: 201
- id: 5
customer_id: 19
name: Wish List
is_public: false
token: 02d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 7
product_id: 173
- id: 8
product_id: 176
meta:
pagination:
total: 0
count: 5
per_page: 50
current_page: 1
total_pages: 0
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'500':
description: Internal server error.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
post:
tags:
- Wishlists
summary: BigCommerce Create a Wishlist
description: >-
Creates a wishlist and wishlist item. More than one item can be added in
the POST.
**Required Fields**
* name
* customer_id
operationId: createWishlist
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/wishlist_Post'
required: true
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/wishlist_Full'
meta:
type: object
properties: {}
additionalProperties: true
description: Response metadata.
example:
data:
id: 30
customer_id: 10
name: Christmas List
is_public: true
token: d2d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 44
product_id: 77
variant_id: 1
- id: 45
product_id: 80
variant_id: 1
- id: 46
product_id: 81
variant_id: 1
- id: 47
product_id: 86
variant_id: 1
- id: 48
product_id: 88
variant_id: 1
meta: {}
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'500':
description: Internal server error.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
/wishlists/{wishlist_id}/items/{item_id}:
parameters:
- $ref: '#/components/parameters/WishlistID'
- $ref: '#/components/parameters/Accept'
- name: item_id
in: path
required: true
schema:
type: integer
format: int32
delete:
tags:
- Wishlists Items
summary: BigCommerce Delete Wishlist Item
description: Deletes a wishlist item.
operationId: deleteWishlistItem
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/wishlist_Full'
meta:
type: object
properties: {}
additionalProperties: true
description: Response metadata.
example:
data:
id: 30
customer_id: 10
name: Christmas List
is_public: true
token: d2d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 44
product_id: 77
variant_id: 1
- id: 45
product_id: 80
variant_id: 1
- id: 46
product_id: 81
variant_id: 1
- id: 47
product_id: 86
variant_id: 1
- id: 48
product_id: 88
variant_id: 1
meta: {}
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'404':
description: Wishlist not found.
content:
application/json:
schema:
type: object
'500':
description: Internal server error.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
/wishlists/{wishlist_id}:
parameters:
- $ref: '#/components/parameters/WishlistID'
- $ref: '#/components/parameters/Accept'
get:
tags:
- Wishlists
summary: BigCommerce Get a Wishlist
description: Returns a single wishlist.
operationId: getWishlist
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/wishlist_Full'
meta:
type: object
properties: {}
additionalProperties: true
description: Response metadata.
example:
data:
id: 30
customer_id: 10
name: Christmas List
is_public: true
token: d2d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 44
product_id: 77
variant_id: 1
- id: 45
product_id: 80
variant_id: 1
- id: 46
product_id: 81
variant_id: 1
- id: 47
product_id: 86
variant_id: 1
- id: 48
product_id: 88
variant_id: 1
meta: {}
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'404':
description: Wishlist not found.
content:
application/json:
schema:
type: object
'500':
description: Internal server error.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
put:
tags:
- Wishlists
summary: BigCommerce Update a Wishlist
description: >-
Updates a wishlist.
Use this endpoint to update existing wishlist items, change the
wishlistʼs name and whether the wishlist is available publicly. To add
or delete a wishlist item, see [Wishlist
Items](/docs/rest-management/wishlists/wishlists-items).
operationId: updateWishlist
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/wishlist_Put'
required: true
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/wishlist_Full'
meta:
type: object
properties: {}
additionalProperties: true
description: Response metadata.
example:
data:
id: 30
customer_id: 10
name: Christmas List
is_public: true
token: d2d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 44
product_id: 77
variant_id: 1
- id: 45
product_id: 80
variant_id: 1
- id: 46
product_id: 81
variant_id: 1
- id: 47
product_id: 86
variant_id: 1
- id: 48
product_id: 88
variant_id: 1
meta: {}
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'500':
description: Internal server error.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
delete:
tags:
- Wishlists
summary: BigCommerce Delete a Wishlist
description: Deletes a wishlist.
operationId: deleteWishlist
responses:
'204':
description: ''
content: {}
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'500':
description: Internal server error.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
/wishlists/{wishlist_id}/items:
parameters:
- $ref: '#/components/parameters/WishlistID'
- $ref: '#/components/parameters/Accept'
post:
tags:
- Wishlists Items
summary: BigCommerce Add Wishlist Item
description: Adds a wishlist item. More than one item can be added at a time.
operationId: addWishlistItem
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/wishlistItem_Post'
required: false
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/wishlist_Full'
meta:
type: object
properties: {}
additionalProperties: true
description: Response metadata.
example:
data:
id: 30
customer_id: 10
name: Christmas List
is_public: true
token: d2d55481-13eb-4d1e-9d79-9062b518570d
items:
- id: 44
product_id: 77
variant_id: 1
- id: 45
product_id: 80
variant_id: 1
- id: 46
product_id: 81
variant_id: 1
- id: 47
product_id: 86
variant_id: 1
- id: 48
product_id: 88
variant_id: 1
meta: {}
'401':
description: Authentication information is missing or invalid.
content:
application/json:
schema:
title: Error
type: object
properties:
status:
type: integer
format: int32
title:
type: string
type:
type: string
'404':
description: Wishlist not found.
content: {}
'500':
description: Internal server error.
content: {}
components:
schemas:
wishlist_Post:
title: wishlist_Post
required:
- customer_id
type: object
properties:
customer_id:
type: integer
description: The customer id.
format: int32
example: 12
is_public:
type: boolean
description: Whether the wishlist is available to the public.
example: false
name:
type: string
description: The title of the wishlist.
example: School Shopping
items:
type: array
description: Array of wishlist items.
items:
title: Add item to wishlist
type: object
properties:
product_id:
type: integer
description: The ID of the product.
format: int32
example: 12
variant_id:
type: integer
description: The variant ID of the product.
format: int32
example: 152
x-internal: false
wishlist_Put:
title: wishlist_Put
required:
- customer_id
- items
type: object
properties:
customer_id:
type: integer
description: The customer ID. A read-only value.
format: int32
is_public:
type: boolean
description: Whether the wishlist is available to the public.
name:
type: string
description: The title of the wishlist.
items:
type: array
description: Array of wishlist items.
items:
title: Wishlist item
type: object
properties:
id:
type: integer
description: The ID of the item.
format: int32
example: 12
product_id:
type: integer
description: The ID of the product.
format: int32
example: 55
variant_id:
type: integer
description: The variant ID of the product.
format: int32
example: 22
x-internal: false
wishlist_Full:
title: wishlist_Full
type: object
properties:
id:
type: integer
description: Wishlist ID, provided after creating a wishlist with a POST.
format: int32
example: 30
customer_id:
type: integer
description: The ID the customer to which the wishlist belongs.
format: int32
example: 12
name:
type: string
description: The name of the wishlist.
example: Christmas List
is_public:
type: boolean
description: Whether the wishlist is available to the public.
example: true
token:
type: string
description: >-
The token of the wishlist. This is created internally within
BigCommerce. The wishlist ID is to be used for external apps.
Read-Only.
format: uuid
example: 02d55481-13eb-4d1e-9d79-9062b518570d
items:
type: array
description: Array of wishlist items.
items:
$ref: '#/components/schemas/wishlistItem_Full'
x-internal: false
wishlistItem_Full:
title: wishlistItem_Full
type: object
properties:
id:
type: integer
description: The ID of the item.
format: int32
example: 12
product_id:
type: integer
description: The ID of the product.
format: int32
example: 55
variant_id:
type: integer
description: The variant ID of the product.
format: int32
example: 22
x-internal: false
wishlistItem_Post:
type: object
title: wishlistItem_Post
properties:
items:
type: array
items:
type: object
properties:
product_id:
type: integer
example: 12
variant_id:
type: integer
example: 152
x-examples:
example-1:
items:
- product_id: 12
variant_id: 152
pagination:
title: pagination
type: object
properties:
total:
type: integer
description: Total number of items in the result set.
format: int32
count:
type: integer
description: Total number of items in the collection response.
format: int32
per_page:
type: integer
description: >-
The amount of items returned in the collection per page, controlled
by the limit parameter.
format: int32
current_page:
type: integer
description: The page you are currently on within the collection.
format: int32
total_pages:
type: integer
description: The total number of pages in the collection.
format: int32
description: Data about the response, including pagination and collection totals.
x-internal: false
metaCollection:
title: metaCollection
type: object
properties:
pagination:
$ref: '#/components/schemas/pagination'
x-internal: false
parameters:
WishlistID:
name: wishlist_id
in: path
description: ID of the Wishlist.
required: true
schema:
type: integer
format: int32
Accept:
name: Accept
in: header
required: true
description: >-
The [MIME
type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
of the response body.
schema:
type: string
default: application/json
ContentType:
name: Content-Type
in: header
required: true
description: >-
The [MIME
type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
of the request body.
schema:
type: string
default: application/json
securitySchemes:
X-Auth-Token:
name: X-Auth-Token
description: >-
### OAuth scopes
| UI Name | Permission | Parameter |
|:--|:--|:-|
| Customers | modify | `store_v2_customers` |
| Customers | read-only | `store_v2_customers_read_only` |
### Authentication header
| Header | Argument | Description |
|:-|:|:|
| `X-Auth-Token` | `access_token` | For more about API accounts that
generate `access_token`s, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts). |
### Further reading
For example requests and more information about authenticating
BigCommerce APIs, see [Authentication and Example
Requests](/docs/start/authentication#x-auth-token-header-example-requests).
For more about BigCommerce OAuth scopes, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts#oauth-scopes).
For a list of API status codes, see [API Status
Codes](/docs/start/about/status-codes).
type: apiKey
in: header