docs: add clarification for set cart's customer API route (#13506)

2025-09-15 14:32:36 +03:00
parent 2ceed66b4d
commit 9f7df88c84
33 changed files with 92 additions and 32 deletions
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_carts_{id}_customer/post.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_carts_{id}_customer/post.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to set the cart's customer
 sdk.store.cart.transferCart("cart_123")
 .then(({ cart }) => {
  console.log(cart)
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me/get.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me/get.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to retrieve their details
 sdk.store.customer.retrieve()
 .then(({ customer }) => {
  console.log(customer)
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me/post.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me/post.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to update their details
 sdk.store.customer.update({
  first_name: "John"
 })
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses/get.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses/get.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to list their addresses
 sdk.store.customer.listAddress()
 .then(({ addresses, count, offset, limit }) => {
  console.log(addresses)
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses/post.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses/post.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to create an address
 sdk.store.customer.createAddress({
  country_code: "us"
 })
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/delete.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/delete.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to delete their address
 sdk.store.customer.deleteAddress("caddr_123")
 .then(({ deleted, parent: customer }) => {
  console.log(customer)
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/get.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/get.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to retrieve their address
 sdk.store.customer.retrieveAddress(
  "caddr_123"
 )
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/post.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/post.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to update their address
 sdk.store.customer.updateAddress(
  "caddr_123",
  {
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_orders/get.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_orders/get.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to list their orders
 sdk.store.order.list()
 .then(({ orders, count, offset, limit }) => {
  console.log(orders)
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_orders_{id}_transfer_cancel/post.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_orders_{id}_transfer_cancel/post.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to cancel the order transfer
 sdk.store.order.cancelTransfer(
  "order_123",
  {},
--- a/www/apps/api-reference/specs/store/code_samples/JavaScript/store_orders_{id}_transfer_request/post.js
+++ b/www/apps/api-reference/specs/store/code_samples/JavaScript/store_orders_{id}_transfer_request/post.js
@@ -12,6 +12,7 @@ export const sdk = new Medusa({
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })

+// TODO must be authenticated as the customer to request the order transfer
 sdk.store.order.requestTransfer(
  "order_123",
  {
--- a/www/apps/api-reference/specs/store/code_samples/Shell/store_carts_{id}_customer/post.sh
+++ b/www/apps/api-reference/specs/store/code_samples/Shell/store_carts_{id}_customer/post.sh
@@ -1,2 +1,3 @@
 curl -X POST '{backend_url}/store/carts/{id}/customer' \
+-H 'Authorization: Bearer {access_token}' \
 -H 'x-publishable-api-key: {your_publishable_api_key}'
--- a/www/apps/api-reference/specs/store/code_samples/Shell/store_customers_me_addresses_{address_id}/delete.sh
+++ b/www/apps/api-reference/specs/store/code_samples/Shell/store_customers_me_addresses_{address_id}/delete.sh
@@ -1,3 +1,3 @@
 curl -X DELETE '{backend_url}/store/customers/me/addresses/{address_id}' \
-H 'x-publishable-api-key: {your_publishable_api_key}' \
-H 'Authorization: Bearer {access_token}'
+-H 'Authorization: Bearer {access_token}' \
+-H 'x-publishable-api-key: {your_publishable_api_key}'
--- a/www/apps/api-reference/specs/store/code_samples/Shell/store_orders/get.sh
+++ b/www/apps/api-reference/specs/store/code_samples/Shell/store_orders/get.sh
@@ -1,2 +1,3 @@
 curl '{backend_url}/store/orders' \
+-H 'Authorization: Bearer {access_token}' \
 -H 'x-publishable-api-key: {your_publishable_api_key}'
--- a/www/apps/api-reference/specs/store/code_samples/Shell/store_orders_{id}_transfer_cancel/post.sh
+++ b/www/apps/api-reference/specs/store/code_samples/Shell/store_orders_{id}_transfer_cancel/post.sh
@@ -1,2 +1,3 @@
 curl -X POST '{backend_url}/store/orders/{id}/transfer/cancel' \
+-H 'Authorization: Bearer {access_token}' \
 -H 'x-publishable-api-key: {your_publishable_api_key}'
--- a/www/apps/api-reference/specs/store/code_samples/Shell/store_orders_{id}_transfer_request/post.sh
+++ b/www/apps/api-reference/specs/store/code_samples/Shell/store_orders_{id}_transfer_request/post.sh
@@ -1,2 +1,3 @@
 curl -X POST '{backend_url}/store/orders/{id}/transfer/request' \
+-H 'Authorization: Bearer {access_token}' \
 -H 'x-publishable-api-key: {your_publishable_api_key}'
--- a/www/apps/api-reference/specs/store/openapi.full.yaml
+++ b/www/apps/api-reference/specs/store/openapi.full.yaml
@@ -1265,13 +1265,13 @@ paths:
  /store/carts/{id}/customer:
    post:
      operationId: PostCartsIdCustomer
-      summary: Set Cart's Customer
-      x-sidebar-summary: Set Customer
-      description: Set the customer of the cart. This is useful when you create the cart for a guest customer, then they log in with their account.
+      summary: Change Cart's Customer to Logged-in Customer
+      x-sidebar-summary: Change Customer
+      description: Change the cart's customer to the currently logged-in customer. This is useful when you create the cart for a guest customer, then they log in with their account.
      externalDocs:
        url: https://docs.medusajs.com/resources/storefront-development/cart/update#set-carts-customer
        description: 'Storefront guide: How to set the cart''s customer.'
-      x-authenticated: false
+      x-authenticated: true
      parameters:
        - name: id
          in: path
@@ -1318,6 +1318,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to set the cart's customer
            sdk.store.cart.transferCart("cart_123")
            .then(({ cart }) => {
              console.log(cart)
@@ -1326,6 +1327,7 @@ paths:
          label: cURL
          source: |-
            curl -X POST '{backend_url}/store/carts/{id}/customer' \
+            -H 'Authorization: Bearer {access_token}' \
            -H 'x-publishable-api-key: {your_publishable_api_key}'
      tags:
        - Carts
@@ -1361,6 +1363,9 @@ paths:
          description: Emitted when the customer in the cart is transferred.
          deprecated: false
          since: 2.8.0
+      security:
+        - cookie_auth: []
+        - jwt_token: []
  /store/carts/{id}/gift-cards:
    post:
      operationId: PostCartsIdGiftCards
@@ -3349,6 +3354,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to retrieve their details
            sdk.store.customer.retrieve()
            .then(({ customer }) => {
              console.log(customer)
@@ -3433,6 +3439,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to update their details
            sdk.store.customer.update({
              first_name: "John"
            })
@@ -3623,6 +3630,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to list their addresses
            sdk.store.customer.listAddress()
            .then(({ addresses, count, offset, limit }) => {
              console.log(addresses)
@@ -3708,6 +3716,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to create an address
            sdk.store.customer.createAddress({
              country_code: "us"
            })
@@ -3811,6 +3820,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to retrieve their address
            sdk.store.customer.retrieveAddress(
              "caddr_123"
            )
@@ -3904,6 +3914,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to update their address
            sdk.store.customer.updateAddress(
              "caddr_123",
              {
@@ -4001,6 +4012,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to delete their address
            sdk.store.customer.deleteAddress("caddr_123")
            .then(({ deleted, parent: customer }) => {
              console.log(customer)
@@ -4009,8 +4021,8 @@ paths:
          label: cURL
          source: |-
            curl -X DELETE '{backend_url}/store/customers/me/addresses/{address_id}' \
-            -H 'x-publishable-api-key: {your_publishable_api_key}' \
-            -H 'Authorization: Bearer {access_token}'
+            -H 'Authorization: Bearer {access_token}' \
+            -H 'x-publishable-api-key: {your_publishable_api_key}'
      tags:
        - Customers
      responses:
@@ -4343,6 +4355,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to list their orders
            sdk.store.order.list()
            .then(({ orders, count, offset, limit }) => {
              console.log(orders)
@@ -4351,6 +4364,7 @@ paths:
          label: cURL
          source: |-
            curl '{backend_url}/store/orders' \
+            -H 'Authorization: Bearer {access_token}' \
            -H 'x-publishable-api-key: {your_publishable_api_key}'
      tags:
        - Orders
@@ -4643,6 +4657,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to cancel the order transfer
            sdk.store.order.cancelTransfer(
              "order_123",
              {},
@@ -4657,6 +4672,7 @@ paths:
          label: cURL
          source: |-
            curl -X POST '{backend_url}/store/orders/{id}/transfer/cancel' \
+            -H 'Authorization: Bearer {access_token}' \
            -H 'x-publishable-api-key: {your_publishable_api_key}'
      tags:
        - Orders
@@ -4844,6 +4860,7 @@ paths:
              publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
            })

+            // TODO must be authenticated as the customer to request the order transfer
            sdk.store.order.requestTransfer(
              "order_123",
              {
@@ -4861,6 +4878,7 @@ paths:
          label: cURL
          source: |-
            curl -X POST '{backend_url}/store/orders/{id}/transfer/request' \
+            -H 'Authorization: Bearer {access_token}' \
            -H 'x-publishable-api-key: {your_publishable_api_key}'
      tags:
        - Orders
--- a/www/apps/api-reference/specs/store/paths/store_carts_{id}_customer.yaml
+++ b/www/apps/api-reference/specs/store/paths/store_carts_{id}_customer.yaml
@@ -1,15 +1,16 @@
 post:
  operationId: PostCartsIdCustomer
-  summary: Set Cart's Customer
-  x-sidebar-summary: Set Customer
+  summary: Change Cart's Customer to Logged-in Customer
+  x-sidebar-summary: Change Customer
  description: >-
-    Set the customer of the cart. This is useful when you create the cart for a
-    guest customer, then they log in with their account.
+    Change the cart's customer to the currently logged-in customer. This is
+    useful when you create the cart for a guest customer, then they log in with
+    their account.
  externalDocs:
    url: >-
      https://docs.medusajs.com/resources/storefront-development/cart/update#set-carts-customer
    description: 'Storefront guide: How to set the cart''s customer.'
-  x-authenticated: false
+  x-authenticated: true
  parameters:
    - name: id
      in: path
@@ -88,3 +89,6 @@ post:
      description: Emitted when the customer in the cart is transferred.
      deprecated: false
      since: 2.8.0
+  security:
+    - cookie_auth: []
+    - jwt_token: []