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 Cart API integration spec and OpenAPI documentation

Damian Legawiecd4a8b0318e92
diff --git a/api/spec/integration/spree/api/v3/store/cart_spec.rb b/api/spec/integration/spree/api/v3/store/cart_spec.rb
new file mode 100644
index 0000000000..c1e7441ec4
--- /dev/null
+++ b/api/spec/integration/spree/api/v3/store/cart_spec.rb
@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ path '/api/v3/store/cart' do
+ get 'Get current cart' do
+ tags 'Cart'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Returns the current shopping cart (incomplete order).
+ Authenticate via JWT token for logged-in users or via order_token parameter for guests.
+ DESC
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer JWT token for authenticated customers'
+ parameter name: :order_token, in: :query, type: :string, required: false,
+ description: 'Order token for guest checkout'
+
+ response '200', 'cart found (guest)' do
+ let(:cart) { create(:order_with_line_items, store: store) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:order_token) { cart.token }
+
+ schema type: :object,
+ allOf: [
+ { '$ref' => '#/components/schemas/StoreOrder' },
+ { type: :object, properties: { token: { type: :string } } }
+ ]
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['number']).to eq(cart.number)
+ expect(data['token']).to eq(cart.token)
+ expect(data['line_items']).to be_present
+ end
+ end
+
+ response '200', 'cart found (authenticated)' do
+ let!(:cart) { create(:order_with_line_items, store: store, user: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema type: :object,
+ allOf: [
+ { '$ref' => '#/components/schemas/StoreOrder' },
+ { type: :object, properties: { token: { type: :string } } }
+ ]
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['number']).to eq(cart.number)
+ end
+ end
+
+ response '404', 'no cart found' do
+ let(:'x-spree-api-key') { api_key.token }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('record_not_found')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/store/cart/associate' do
+ patch 'Associate guest cart with authenticated user' do
+ tags 'Cart'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Associates a guest cart with the currently authenticated user.
+ Requires both JWT authentication and an order token.
+ The order must not be completed and must not belong to another user.
+ DESC
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true,
+ description: 'Bearer JWT token (required)'
+ parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,
+ description: 'Order token (can also be passed as query param)'
+ parameter name: :order_token, in: :query, type: :string, required: false,
+ description: 'Order token (alternative to header)'
+
+ response '200', 'cart associated successfully' do
+ let(:guest_cart) { create(:order_with_line_items, store: store, user: nil) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_token) { guest_cart.token }
+
+ schema type: :object,
+ allOf: [
+ { '$ref' => '#/components/schemas/StoreOrder' },
+ { type: :object, properties: { token: { type: :string } } }
+ ]
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['number']).to eq(guest_cart.number)
+ expect(guest_cart.reload.user).to eq(user)
+ end
+ end
+
+ response '401', 'unauthorized - JWT required' do
+ let(:guest_cart) { create(:order_with_line_items, store: store, user: nil) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { '' }
+ let(:order_token) { guest_cart.token }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('authentication_required')
+ end
+ end
+
+ response '403', 'cart belongs to another user' do
+ let(:other_user) { create(:user) }
+ let(:other_cart) { create(:order_with_line_items, store: store, user: other_user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_token) { other_cart.token }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('access_denied')
+ end
+ end
+
+ response '404', 'cart not found' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_token) { 'invalid_token' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('record_not_found')
+ end
+ end
+
+ response '422', 'cart already completed' do
+ let(:completed_order) { create(:completed_order_with_totals, store: store, user: nil) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_token) { completed_order.token }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['error']['code']).to eq('order_already_completed')
+ end
+ end
+ end
+ end
+end
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 9e19bad2d1..619371001b 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -621,6 +621,126 @@ paths:
type: string
password_confirmation:
type: string
+ "/api/v3/store/cart":
+ get:
+ summary: Get current cart
+ tags:
+ - Cart
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |
+ Returns the current shopping cart (incomplete order).
+ Authenticate via JWT token for logged-in users or via order_token parameter for guests.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer JWT token for authenticated customers
+ schema:
+ type: string
+ - name: order_token
+ in: query
+ required: false
+ description: Order token for guest checkout
+ schema:
+ type: string
+ responses:
+ '200':
+ description: cart found
+ content:
+ application/json:
+ schema:
+ allOf:
+ - "$ref": "#/components/schemas/StoreOrder"
+ - type: object
+ properties:
+ token:
+ type: string
+ description: Order token for guest access
+ '404':
+ description: no cart found
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/cart/associate":
+ patch:
+ summary: Associate guest cart with authenticated user
+ tags:
+ - Cart
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |
+ Associates a guest cart with the currently authenticated user.
+ Requires both JWT authentication and an order token.
+ The order must not be completed and must not belong to another user.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer JWT token (required)
+ schema:
+ type: string
+ - name: x-spree-order-token
+ in: header
+ required: false
+ description: Order token (can also be passed as query param)
+ schema:
+ type: string
+ - name: order_token
+ in: query
+ required: false
+ description: Order token (alternative to header)
+ schema:
+ type: string
+ responses:
+ '200':
+ description: cart associated successfully
+ content:
+ application/json:
+ schema:
+ allOf:
+ - "$ref": "#/components/schemas/StoreOrder"
+ - type: object
+ properties:
+ token:
+ type: string
+ '401':
+ description: unauthorized - JWT required
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '403':
+ description: cart belongs to another user
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '404':
+ description: cart not found
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '422':
+ description: cart already completed
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
"/api/v3/store/orders/{order_id}/line_items":
post:
summary: Add item to cart
@@ -2113,6 +2233,8 @@ tags:
description: Individual categories
- name: Countries
description: Available shipping countries
+- name: Cart
+ description: Current shopping cart management
- name: Orders
description: Shopping cart and checkout
- name: Line Items