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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add API docs for wishlists
Matthew Kennedy1cc5b5c291f6
diff --git a/api/docs/v2/storefront/index.yaml b/api/docs/v2/storefront/index.yamlindex 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: truecomponents:securitySchemes:bearerAuth:@@ -13900,21 +14468,54 @@ components:example: 1080description: Actual height of imageUser:+ 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: objectproperties:id:type: string- example: "1"type:type: string- default: userattributes:+ $ref: '#/components/schemas/UserAttributes'+ relationships:type: objectproperties:- email:- type: string- format: email- example: [email protected]+ 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: arrayitems:oneOf:- - $ref: '#/components/schemas/Relation'+ - $ref: '#/components/schemas/Relation'CmsHeroImageSection:type: objectproperties:@@ -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: stringexample: '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-usCmsPageIncludeParam:name: includein: query@@ -15797,7 +16524,7 @@ components:LocaleParam:name: localein: 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: stringexample: en@@ -15816,7 +16543,7 @@ components:description: Taxon Permalinkschema:type: string- example: "categories/women"+ example: categories/womenPageParam:name: pagein: query@@ -15917,6 +16644,13 @@ components:type: stringdescription: Pass `default_billing_address` and/or `default_shipping_address` as value to include selected addresses informationexample: '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: queryname: '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: stringresponses:404NotFound:description: Resource not found@@ -15994,7 +16735,6 @@ components:type: stringexample: 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