Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Add API docs for wishlists

Matthew Kennedy1cc5b5c291f6
diff --git a/api/docs/v2/storefront/index.yaml b/api/docs/v2/storefront/index.yaml
index 169cab49ab..587c6d6c8d 100644
--- a/api/docs/v2/storefront/index.yaml
+++ b/api/docs/v2/storefront/index.yaml
@@ -13425,6 +13425,574 @@ paths:
'404':
$ref: '#/components/responses/404NotFound'
summary: Get Menu Details
+ /api/v2/storefront/wishlists:
+ get:
+ description: Returns a list of wishlists for the current user in the current store.
+ summary: List all wishlists
+ tags:
+ - Wishlists
+ operationId: list-wishlists-for-current-user
+ parameters:
+ - $ref: '#/components/parameters/WishlistIncludeParam'
+ - $ref: '#/components/parameters/WishlistSparseFieldsParam'
+ - $ref: '#/components/parameters/PerPageParam'
+ responses:
+ '200':
+ description: Returns a hash with a data property that contains an array of wishlists. Each entry in the array is a separate wishlist object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Wishlists'
+ examples:
+ Standard response:
+ value:
+ data:
+ - id: '21'
+ type: wishlist
+ attributes:
+ token: snK3N5nCx2GV3fWzRV4rH9VE
+ name: Black Friday
+ is_private: true
+ is_default: false
+ relationships:
+ wished_items:
+ data: []
+ - id: '22'
+ type: wishlist
+ attributes:
+ token: TG5gyZjUbg4L1RY75ekJ3qmM
+ name: Fathers Day
+ is_private: true
+ is_default: false
+ relationships:
+ wished_items:
+ data: []
+ - id: '23'
+ type: wishlist
+ attributes:
+ token: LhCmvs8XryASJz7SmWQ6vvJW
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ relationships:
+ wished_items:
+ data:
+ - id: '11'
+ type: wished_variant
+ meta:
+ count: 3
+ total_count: 3
+ total_pages: 1
+ links:
+ self: 'http://localhost:3000/api/v2/storefront/wishlists'
+ next: 'http://localhost:3000/api/v2/storefront/wishlists?page=1'
+ prev: 'http://localhost:3000/api/v2/storefront/wishlists?page=1'
+ last: 'http://localhost:3000/api/v2/storefront/wishlists?page=1'
+ first: 'http://localhost:3000/api/v2/storefront/wishlists?page=1'
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ post:
+ description: Creates a new wishlist for current user in the current store.
+ summary: Create a wishlist
+ tags:
+ - Wishlists
+ operationId: create-wishlist
+ responses:
+ '200':
+ description: Returns the new wishlist object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Wishlist'
+ examples:
+ Standard response:
+ value:
+ data:
+ id: '28'
+ type: wishlist
+ attributes:
+ token: 1inBHcJnxBrVEMAZb9esRqZP
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ relationships:
+ wished_items:
+ data: []
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ description: The wishlist name.
+ is_private:
+ type: boolean
+ description: Whether the wishlist is public or private. Defaults to true (private).
+ is_default:
+ type: boolean
+ description: Whether the wishlist is set to the users default wishlist for the current store. Defaults to false.
+ required:
+ - name
+ examples:
+ Create wishlist:
+ value:
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ '/api/v2/storefront/wishlists/{token}':
+ get:
+ description: 'Retrieves the details of an existing wishlist. Supply the unique wishlist token, and we will return the corresponding wishlist information.'
+ summary: Retrieve a wishlist
+ tags:
+ - Wishlists
+ operationId: get-wishlist-details-for-current-user
+ parameters:
+ - $ref: '#/components/parameters/Token'
+ - $ref: '#/components/parameters/WishlistIncludeParam'
+ - $ref: '#/components/parameters/WishlistSparseFieldsParam'
+ responses:
+ '200':
+ description: Returns the requested wishlist object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Wishlist'
+ examples:
+ Standard response:
+ value:
+ data:
+ id: '28'
+ type: wishlist
+ attributes:
+ token: 1inBHcJnxBrVEMAZb9esRqZP
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ relationships:
+ wished_items:
+ data:
+ - id: '14'
+ type: wished_variant
+ include=wished_items:
+ value:
+ data:
+ id: '28'
+ type: wishlist
+ attributes:
+ token: 1inBHcJnxBrVEMAZb9esRqZP
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ relationships:
+ wished_items:
+ data:
+ - id: '14'
+ type: wished_variant
+ included:
+ - id: '14'
+ type: wished_variant
+ attributes:
+ quantity: 7
+ price: '26.99'
+ total: '188.93'
+ display_price: $26.99
+ display_total: $188.93
+ relationships:
+ variant:
+ data:
+ id: '149'
+ type: variant
+ wishlist:
+ data:
+ id: '28'
+ type: wishlist
+ 'fields[wishlist]=name,is_private':
+ value:
+ data:
+ id: '29'
+ type: wishlist
+ attributes:
+ name: Birthday Ideas!
+ is_private: true
+ relationships: {}
+ include=wished_items.variant:
+ value:
+ data:
+ id: '29'
+ type: wishlist
+ attributes:
+ token: vmJtMiMozBdFtn1VkdJ8dYen
+ name: Birthday Ideas!
+ is_private: true
+ is_default: true
+ relationships:
+ wished_items:
+ data:
+ - id: '15'
+ type: wished_variant
+ included:
+ - id: '149'
+ type: variant
+ attributes:
+ sku: JacketsandCoats_downjacketwithhood_26.99_dark_blue_xs
+ weight: '0.0'
+ height: null
+ width: null
+ depth: null
+ is_master: false
+ options_text: 'Color: dark_blue, Size: XS'
+ purchasable: true
+ in_stock: true
+ backorderable: true
+ currency: USD
+ price: '26.99'
+ display_price: $26.99
+ compare_at_price: null
+ display_compare_at_price: null
+ relationships:
+ product:
+ data:
+ id: '33'
+ type: product
+ images:
+ data: []
+ option_values:
+ data:
+ - id: '13'
+ type: option_value
+ - id: '23'
+ type: option_value
+ - id: '15'
+ type: wished_variant
+ attributes:
+ quantity: 7
+ price: '26.99'
+ total: '188.93'
+ display_price: $26.99
+ display_total: $188.93
+ relationships:
+ variant:
+ data:
+ id: '149'
+ type: variant
+ wishlist:
+ data:
+ id: '29'
+ type: wishlist
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ put:
+ description: Updates the specific wishlist by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
+ summary: Update a wishlist
+ tags:
+ - Wishlists
+ operationId: update-wishlist
+ requestBody:
+ required: true
+ content:
+ application/vnd.api+json:
+ schema:
+ type: object
+ properties:
+ wishlist:
+ type: object
+ properties:
+ name:
+ type: string
+ description: Change the wishlist name.
+ is_private:
+ type: boolean
+ description: Set the wishlist to public or private.
+ is_default:
+ type: boolean
+ description: Make this wishlist the default wishlist.
+ examples:
+ Update Name:
+ value:
+ wishlist:
+ name: Birthday Ideas
+ Set to Private:
+ value:
+ wishlist:
+ is_private: true
+ Make Default:
+ value:
+ wishlist:
+ is_default: true
+ description: ''
+ parameters:
+ - $ref: '#/components/parameters/Token'
+ responses:
+ '200':
+ description: Returns the updated wishlist object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Wishlist'
+ examples:
+ Standard Response:
+ value:
+ data:
+ id: '28'
+ type: wishlist
+ attributes:
+ token: 1inBHcJnxBrVEMAZb9esRqZP
+ name: Birthday Ideas
+ is_private: true
+ is_default: true
+ relationships:
+ wished_items:
+ data:
+ - id: '14'
+ type: wished_variant
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ delete:
+ description: Delete a wishlist.
+ summary: Delete a wishlist
+ tags:
+ - Wishlists
+ operationId: delete-wishlist
+ parameters:
+ - $ref: '#/components/parameters/Token'
+ responses:
+ '200':
+ description: Returns the deleted wishlist object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Wishlist'
+ examples:
+ Standard Response:
+ value:
+ data:
+ id: '26'
+ type: wishlist
+ attributes:
+ token: tAnaaejJ199JQF3qFWfXLgoE
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ relationships:
+ wished_items:
+ data: []
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ /api/v2/storefront/wishlists/default:
+ get:
+ description: |-
+ Returns the default wishlist for the current user, in the current store.
+
+ If the user does not have a default wishlist in the current store one will be created on request.
+ summary: Retrieve the default wishlist
+ tags:
+ - Wishlists
+ operationId: get-default-wishlist
+ parameters:
+ - $ref: '#/components/parameters/WishlistIncludeParam'
+ - $ref: '#/components/parameters/WishlistSparseFieldsParam'
+ responses:
+ '200':
+ description: Returns the default wishlist object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Wishlist'
+ examples:
+ Standard response:
+ value:
+ data:
+ id: '29'
+ type: wishlist
+ attributes:
+ token: vmJtMiMozBdFtn1VkdJ8dYen
+ name: My Wishlist
+ is_private: false
+ is_default: true
+ relationships:
+ wished_items:
+ data: []
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ '/api/v2/storefront/wishlists/{token}/add_item':
+ post:
+ summary: Add an item to a wishlist
+ description: |-
+ The add item 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 the variant price and total for the variant in the desired quantity.
+ tags:
+ - Wishlists
+ 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 retuned quantity value will always be 1, allowing the add-to-cart and pricing to accuratly reflect the single representation of the wished item.
+
+ If the wishlist system you are building allows for setting quantity, add the quantity attribute to the request body, and ensure that it is an integer value greater than zero.
+ responses:
+ '200':
+ description: Returns the new wished item object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/WishedItem'
+ examples:
+ Standard response:
+ value:
+ data:
+ id: '9'
+ type: wished_variant
+ attributes:
+ quantity: 7
+ price: '28.99'
+ total: '202.93'
+ display_price: $28.99
+ display_total: $202.93
+ relationships:
+ variant:
+ data:
+ id: '149'
+ type: variant
+ wishlist:
+ data:
+ id: '4'
+ type: wishlist
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ parameters:
+ - schema:
+ type: string
+ name: token
+ in: path
+ required: true
+ '/api/v2/storefront/wishlists/{token}/set_item_quantity/{item_id}':
+ patch:
+ description: Sets the wished item quantity.
+ summary: Set item quantity
+ tags:
+ - Wishlists
+ operationId: update-wished-variant-quantity
+ parameters:
+ - $ref: '#/components/parameters/Token'
+ - $ref: '#/components/parameters/ItemId'
+ requestBody:
+ required: true
+ content:
+ application/vnd.api+json:
+ schema:
+ type: object
+ properties:
+ quantity:
+ type: number
+ description: Set the quantity value to an integer greater than 0
+ required:
+ - quantity
+ examples:
+ Add a variant:
+ value:
+ quantity: 7
+ description: ''
+ responses:
+ '200':
+ description: Returns the updated wished item object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/WishedItem'
+ examples:
+ Standard response:
+ value:
+ data:
+ id: '16'
+ type: wished_variant
+ attributes:
+ quantity: 5
+ price: '26.99'
+ total: '134.95'
+ display_price: $26.99
+ display_total: $134.95
+ relationships:
+ variant:
+ data:
+ id: '149'
+ type: variant
+ wishlist:
+ data:
+ id: '30'
+ type: wishlist
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ '/api/v2/storefront/wishlists/{token}/remove_item/{item_id}':
+ delete:
+ description: Removes the wished item from the wishlist.
+ summary: Delete item from wishlist
+ tags:
+ - Wishlists
+ operationId: delete-wished-variant-from-wishlist
+ parameters:
+ - $ref: '#/components/parameters/Token'
+ - $ref: '#/components/parameters/ItemId'
+ responses:
+ '200':
+ description: Returns the deleted wished item object.
+ content:
+ application/vnd.api+json:
+ schema:
+ $ref: '#/components/schemas/Account'
+ '403':
+ $ref: '#/components/responses/403Forbidden'
+ security:
+ - bearerAuth: []
+ parameters:
+ - schema:
+ type: string
+ name: token
+ in: path
+ required: true
+ - schema:
+ type: string
+ name: item_id
+ in: path
+ required: true
components:
securitySchemes:
bearerAuth:
@@ -13900,21 +14468,54 @@ components:
example: 1080
description: Actual height of image
User:
+ required:
+ - data
+ properties:
+ data:
+ $ref: '#/components/schemas/UserAttributesAndRelationships'
+ included:
+ type: array
+ items:
+ anyOf:
+ - $ref: '#/components/schemas/default_billing_address'
+ - $ref: '#/components/schemas/default_shipping_address'
+ UserAttributes:
+ type: object
+ properties:
+ email:
+ type: string
+ store_credits:
+ type: integer
+ completed_orders:
+ type: integer
+ UserAttributesAndRelationships:
type: object
properties:
id:
type: string
- example: "1"
type:
type: string
- default: user
attributes:
+ $ref: '#/components/schemas/UserAttributes'
+ relationships:
type: object
properties:
- email:
- type: string
- format: email
+ default_billing_address:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/Relation'
+ default_shipping_address:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/Relation'
LineItem:
properties:
id:
@@ -15013,7 +15614,7 @@ components:
type: array
items:
oneOf:
- - $ref: '#/components/schemas/Relation'
+ - $ref: '#/components/schemas/Relation'
CmsHeroImageSection:
type: object
properties:
@@ -15748,6 +16349,116 @@ components:
properties:
url:
type: string
+ Wishlist:
+ properties:
+ data:
+ $ref: '#/components/schemas/WishlistAttributesAndRelationships'
+ included:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/WishedItemAttributesAndRelationships'
+ required:
+ - data
+ Wishlists:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/WishlistAttributesAndRelationships'
+ included:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/WishedItemAttributesAndRelationships'
+ meta:
+ $ref: '#/components/schemas/ListMeta'
+ links:
+ $ref: '#/components/schemas/ListLinks'
+ required:
+ - data
+ - meta
+ - links
+ WishlistAttributes:
+ type: object
+ properties:
+ token:
+ type: string
+ name:
+ type: string
+ is_private:
+ type: boolean
+ is_default:
+ type: boolean
+ WishlistAttributesAndRelationships:
+ description: ''
+ type: object
+ properties:
+ id:
+ type: string
+ type:
+ type: string
+ attributes:
+ $ref: '#/components/schemas/WishlistAttributes'
+ relationships:
+ type: object
+ properties:
+ wished_items:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/Relation'
+ WishedItem:
+ properties:
+ data:
+ $ref: '#/components/schemas/WishedItemAttributesAndRelationships'
+ included:
+ type: array
+ items:
+ anyOf:
+ - $ref: '#/components/schemas/VariantAttributesAndRelationships'
+ - $ref: '#/components/schemas/WishlistAttributesAndRelationships'
+ required:
+ - data
+ WishedItemAttributes:
+ type: object
+ properties:
+ quantity:
+ type: integer
+ price:
+ type: string
+ total:
+ type: string
+ display_price:
+ type: string
+ display_total:
+ type: string
+ WishedItemAttributesAndRelationships:
+ type: object
+ properties:
+ id:
+ type: string
+ type:
+ type: string
+ attributes:
+ $ref: '#/components/schemas/WishedItemAttributes'
+ relationships:
+ type: object
+ properties:
+ variant:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/Relation'
+ wishlist:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/Relation'
parameters:
Id:
name: id
@@ -15757,14 +16468,30 @@ components:
schema:
type: string
example: '1'
+ 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
+ ItemId:
+ name: item_id
+ in: path
+ required: true
+ description: The wished item id
+ schema:
+ type: string
+ example: '3'
CmsPageSlug:
- name: cms_page_slug
- in: path
- required: true
- description: CMS Page Slug
- schema:
- type: string
- example: about-us
+ name: cms_page_slug
+ in: path
+ required: true
+ description: CMS Page Slug
+ schema:
+ type: string
+ example: about-us
CmsPageIncludeParam:
name: include
in: query
@@ -15797,7 +16524,7 @@ components:
LocaleParam:
name: locale
in: query
- description: "Pass `locale` as value to fetch the resources with the matching locale for example `?locale=fr`."
+ description: Pass `locale` as value to fetch the resources with the matching locale for example `?locale=fr`.
schema:
type: string
example: en
@@ -15816,7 +16543,7 @@ components:
description: Taxon Permalink
schema:
type: string
- example: "categories/women"
+ example: categories/women
PageParam:
name: page
in: query
@@ -15917,6 +16644,13 @@ components:
type: string
description: Pass `default_billing_address` and/or `default_shipping_address` as value to include selected addresses information
example: 'default_billing_address,default_shipping_address'
+ WishlistIncludeParam:
+ name: include
+ in: query
+ schema:
+ type: string
+ example: include=wished_items.variant
+ description: Specify what related resources (relationships) you would like to receive in the response body. You can also fetch relationships of relationships.
FilterByIds:
in: query
name: 'filter[ids]'
@@ -15973,6 +16707,13 @@ components:
example: '[cart]=total,currency,number'
schema:
type: string
+ WishlistSparseFieldsParam:
+ in: query
+ name: fields
+ description: Specify what attributes for given types you would like to receive in the response body. Response examples are available.
+ example: '[wishlist]=name,is_default'
+ schema:
+ type: string
responses:
404NotFound:
description: Resource not found
@@ -15994,7 +16735,6 @@ components:
type: string
example: You are not authorized to access this page.
default: You are not authorized to access this page.
-
tags:
- name: Account
- name: Cart
@@ -16005,3 +16745,4 @@ tags:
- name: Menus
- name: Products
- name: Taxons
+ - name: Wishlists