Configurable customer address

docs/developer/bulks/bulk-orders.mdx

@@ -237,6 +237,7 @@ mutation OrderBulkCreate(
       "user": {
         "email":"[email protected]"
       },
+      "saveBillingAddress" true,
       "billingAddress": {
         "firstName": "John Saleor",
         "lastName": "Doe Mirumee",

docs/developer/checkout/address.mdx

@@ -424,3 +424,178 @@ The shipping and billing addresses need to be valid when finalizing checkout by
 :::note
 The fields for shipping and billing addresses will be normalized (if needed) on completing the checkout by calling [checkoutComplete](api-reference/checkout/mutations/checkout-complete.mdx) mutation.
 :::
+
+## Customer Address Saving Strategies
+Address updates allow configuring the address-saving strategy for both shipping and billing addresses.
+This setting determines whether the shipping or billing address should be saved in the customer's address book.
+It applies only when the checkout is completed by a logged-in user.
+
+By default, both billing and shipping addresses are saved in the customer's address book.
+
+### Use cases:
+- **External Click & Collect (C&C) addresses:** Prevents collection point addresses from being saved to a customer’s address book.
+- **Customer choice during checkout:** Allows customers to explicitly decide whether to save newly entered addresses to their account.
+
+### Applicable Checkout Mutations
+The default behavior can be adjusted in the following checkout mutations:
+- [checkoutCreate](/api-reference/checkout/mutations/checkout-create.mdx)
+```graphql
+mutation createCheckout($input: CheckoutCreateInput!) {
+  checkoutCreate(input: $input){
+    checkout {
+      id
+    }
+    errors {
+      field
+      code
+    }
+  }
+}
+```
+input data:
+```json {6,16}
+{
+  "input": {
+    "channel": "default-channel",
+    "email": "[email protected]",
+    "lines": [{ "quantity": 1, "variantId": "UHJvZHVjdFZhcmlhbnQ6Mjk3" }],
+    "saveShippingAddress": false,
+    "shippingAddress": {
+      "firstName": "John",
+      "lastName": "Doe",
+      "streetAddress1": "1470  Pinewood Avenue",
+      "city": "Michigan",
+      "postalCode": "49855",
+      "country": "US",
+      "countryArea": "MI"
+    },
+    "saveBillingAddress": true,
+    "billingAddress": {
+      "firstName": "John",
+      "lastName": "Doe",
+      "streetAddress1": "1470  Pinewood Avenue",
+      "city": "Michigan",
+      "postalCode": "49855",
+      "country": "US",
+      "countryArea": "MI"
+    }
+  }
+}
+```
+- [checkoutShippingAddressUpdate](/api-reference/checkout/mutations/checkout-shipping-address-update.mdx)
+```graphql
+mutation checkoutShippingAddressUpdate(
+  $id: ID,
+  $shippingAddress: AddressInput!
+  $saveAddress: Boolean
+){
+  checkoutShippingAddressUpdate(
+    id: $id
+    shippingAddress: $shippingAddress
+    saveAddress: $saveAddress
+  ) {
+    errors {
+      field
+      message
+      code
+    }
+    checkout {
+      id
+      shippingAddress {
+        id
+        postalCode
+        firstName
+        lastName
+        country {
+          code
+        }
+      }
+    }
+  }
+}
+```
+input data:
+```json {4}
+{
+  "id": "Q2hlY2tvdXQ6MjU1MmYxYTctN2Q3MC00ODg5LTg1OWYtNGNiNWNlMGI4Zjhk",
+  "shippingAddress": { "postalCode": "12-333"},
+  "saveAddress": false
+}
+```
+- [checkoutBillingAddressUpdate](/api-reference/checkout/mutations/checkout-billing-address-update.mdx)
+```graphql
+mutation checkoutBillingAddressUpdate(
+  $id: ID,
+  $billingAddress: AddressInput!
+  $saveAddress: Boolean
+){
+  checkoutBillingAddressUpdate(
+    id: $id
+    billingAddress: $billingAddress
+    saveAddress: $saveAddress
+  ) {
+    errors {
+      field
+      message
+      code
+    }
+    checkout {
+      id
+      billingAddress {
+        id
+        postalCode
+        firstName
+        lastName
+        country {
+          code
+        }
+      }
+    }
+  }
+}
+```
+input data:
+```json {4}
+{
+  "id": "Q2hlY2tvdXQ6MjU1MmYxYTctN2Q3MC00ODg5LTg1OWYtNGNiNWNlMGI4Zjhk"
+  "billingAddress": { "postalCode": "12-333"}
+  "saveAddress": false
+}
+```
+
+### Important Notes
+
+The setting is treated as part of the address and cannot be provided independently in the mutation input.
+Attempting to set `saveShippingAddress` or `saveBillingAddress` without including the corresponding
+`shippingAddress` or `billingAddress` will result in an error.
+
+For example, providing `saveShippingAddress` in the `checkoutCreate` mutation without including `shippingAddress` will raise an error:
+```graphql
+mutation createCheckout($input: CheckoutCreateInput!) {
+  checkoutCreate(input: $input){
+    checkout {
+      id
+    }
+    errors {
+      field
+      code
+    }
+  }
+}
+```
+invalid input data:
+```json
+{
+  "input": {
+    "channel": "default-channel"
+    "email": "[email protected]"
+    "lines": [{ "quantity": 1, "variantId": "UHJvZHVjdFZhcmlhbnQ6Mjk3" }]
+    "saveShippingAddress": true
+  }
+}
+```
+
+:::warning
+Any update to the address, even a partial change, resets the `saveAddress` flag to its default behavior.
+To ensure the correct setting is applied, explicitly provide the `saveAddress` value with each update.
+:::

docs/developer/checkout/lifecycle.mdx

@@ -7,7 +7,7 @@ sidebar_label: Lifecycle
 
 Upon creation, `checkout` is assigned to a channel that influences product stock, availability, and price. The channel can not be changed after the checkout is created. Learn more about [Channels](/developer/channels/overview.mdx).
 
-Checkout can be created from [existing orders](/developer/checkout/order-to-checkout.mdx), which is helpful for re-order functionality.
+Checkout can be created from [existing orders](/developer/order/order-to-checkout.mdx), which is helpful for re-order functionality.
 
 ## Updating Checkout
 

docs/developer/order/address.mdx

@@ -0,0 +1,132 @@
+---
+title: Shipping and Billing
+---
+
+## Customer Address Saving Strategies
+Address updates allow configuring the address-saving strategy for both shipping and billing addresses.
+This setting determines whether the shipping or billing address should be saved in the customer's address book.
+This setting takes effect only when a draft order is completed for an existing user.
+If no user is assigned, the setting is ignored.
+
+By default, both billing and shipping addresses are not saved in the customer's address book.
+
+### Use cases:
+- Draft order management: Allows staff user to explicitly decide whether to save newly entered addresses to the customer account.
+
+### Applicable Order Mutations
+The default behavior can be adjusted in the following order mutations:
+- [draftOrderCreate](/api-reference/orders/mutations/draft-order-create)
+```graphql
+mutation DraftOrderCreate(
+  $input: DraftOrderCreateInput!
+) {
+  draftOrderCreate(
+    input: $input
+  ) {
+    order {
+      id
+    }
+  }
+} 
+```
+example input data:
+```json {5,15}
+{
+  "input": {
+    "user": "VXNlcjoxNDM2",
+    "lines": [{ "quantity": 1, "variantId": "UHJvZHVjdFZhcmlhbnQ6Mjk3" }],
+    "saveBillingAddress": true,
+    "billingAddress": {
+      "firstName": "John"
+      "lastName": "Doe"
+      "streetAddress1": "1470  Pinewood Avenue"
+      "city": "Michigan"
+      "postalCode": "49855"
+      "country": "US"
+      "countryArea": "MI"
+    },
+    "saveShippingAddress": false,
+    "shippingAddress": {
+      "firstName": "John"
+      "lastName": "Doe"
+      "streetAddress1": "1470  Pinewood Avenue"
+      "city": "Michigan"
+      "postalCode": "49855"
+      "country": "US"
+      "countryArea": "MI"
+    },
+    "channelId": "Q2hhbm5lbDoyMjQ0",
+  }
+}
+```
+- [draftOrderUpdate](/api-reference/orders/mutations/draft-order-update.mdx)
+```graphql
+mutation DraftOrderUpdate(
+  $id: ID!,
+  $input: DraftOrderInput!,
+) {
+  draftOrderUpdate(
+    id: $id,
+    input: $input
+  ) {
+    order {
+        userEmail
+        externalReference
+    }
+  }
+}
+```
+example input data:
+```json {7}
+{
+  "id": "T3JkZXI6ZGJlZjkxZmQtMjMxZS00ZGNmLTk5ZGMtNGQxOTBhNDFjYTQ1",
+  "input": {
+    "shippingAddress": {
+        "postalCode": "22-356"
+    },
+    "saveShippingAddress": false
+  }
+}
+```
+- [orderBulkCreate](/api-reference/orders/mutations/order-bulk-create.mdx)
+(see the bulk order import [example](/developer/bulks/bulk-orders.mdx))
+
+### Important Notes
+
+The setting is treated as part of the address and cannot be provided independently in the mutation input.
+Attempting to set `saveShippingAddress` or `saveBillingAddress` without including the corresponding
+`shippingAddress` or `billingAddress` will result in an error.
+
+For example, providing `saveShippingAddress` in the `draftOrderUpdate` mutation without including `shippingAddress` will raise an error:
+```graphql
+mutation DraftOrderUpdate(
+  $id: ID!,
+  $input: DraftOrderInput!,
+) {
+  draftOrderUpdate(
+    id: $id,
+    input: $input
+  ) {
+    order {
+      userEmail
+      externalReference
+    }
+  }
+}
+```
+
+invalid input data:
+```json {5}
+{
+  "id": "T3JkZXI6ZGJlZjkxZmQtMjMxZS00ZGNmLTk5ZGMtNGQxOTBhNDFjYTQ1",
+  "input": {
+    "externalReference": "ref-XYZ",
+    "saveShippingAddress": false
+  }
+}
+```
+
+:::warning
+Any update to the address, even a partial change, resets the `saveAddress` flag to its default behavior.
+To ensure the correct setting is applied, explicitly provide the `saveAddress` value with each update.
+::: 

docs/developer/payments/transactions.mdx

@@ -531,7 +531,7 @@ Please remember, that if setting is enabled:
 :::warning
 Checkout will be automatically completed even if some Transactions are still pending and waiting for confirmation from payment provider. Checkouts are considered "covered" as long as the total amount is covered (see when `authorizeStatus` is set to `FULL` in [payment lifecycle docs](/developer/payments/lifecycle.mdx#authorize-status)).
 
-Keep in mind that a pending Transaction might be rejected later, which will result in an unpaid order. To clear orders that remain unpaid you can use [Order Expiration feature](/developer/checkout/order-expiration.mdx)
+Keep in mind that a pending Transaction might be rejected later, which will result in an unpaid order. To clear orders that remain unpaid you can use [Order Expiration feature](/developer/order/order-expiration.mdx)
 :::
 
 :::caution

docs/developer/running-saleor/task-queue.mdx

@@ -38,7 +38,7 @@ Below is a list of Saleor features fired up by celery beat with default schedule
 - Delete empty allocations; 1 hour
 - Delete expired reservations; 1 day
 - Delete outdated event data; 1 day
-- [Expire orders](developer/checkout/order-expiration.mdx); 5 minutes
+- [Expire orders](developer/order/order-expiration.mdx); 5 minutes
 - [Recalculate price for catalog promotions](developer/discounts/promotions.mdx#catalogue-promotions); 30 seconds
 - [Release funds for abandoned checkouts](developer/checkout/lifecycle.mdx#releasing-funds-for-abandoned-checkouts); 10 minutes
 - Remove apps marked as removed; 3 hours
@@ -47,7 +47,7 @@ Below is a list of Saleor features fired up by celery beat with default schedule
 #### Tasks run at specific time:
 - Deactivate expired gift cards; at 0:00 AM
 - [Delete expired checkouts](developer/checkout/lifecycle.mdx#checkout-expiration-and-deletion); at 0:00 AM
-- [Delete expired orders](developer/checkout/order-expiration.mdx); at 2:00 AM base on 
+- [Delete expired orders](developer/order/order-expiration.mdx); at 2:00 AM base on 
 - Delete old exports files; once per day at 1:00 AM
 - Update stocks quantity allocated; once per day at 0:00 AM
 - [Promotion toggle](developer/discounts/promotions.mdx); based on promotion's start date and end date

sidebars/core-concepts.js

@@ -35,9 +35,10 @@ export const coreConcepts = [
   "developer/checkout/api-guide",
 
   title("Orders"),
-  "developer/checkout/order-status",
-  "developer/checkout/order-expiration",
-  "developer/checkout/order-to-checkout",
+  "developer/order/order-status",
+  "developer/order/order-expiration",
+  "developer/order/order-to-checkout",
+  "developer/order/address",
 
   title("Transactions"),
   "developer/payments/overview",

vercel.json

@@ -10,7 +10,7 @@
     },
     {
       "source": "/docs(/3.x|/next)?/developer/order-status",
-      "destination": "/developer/checkout/order-status"
+      "destination": "/developer/order/order-status"
     },
     {
       "source": "/docs(/3.x|/next)?/developer/checkout/finalizing",
@@ -22,7 +22,7 @@
     },
     {
       "source": "/docs(/3.x|/next)?/developer/order-expiration",
-      "destination": "/developer/checkout/order-expiration"
+      "destination": "/developer/order/order-expiration"
     },
     {
       "source": "/docs(/3.x|/next)?(/api-storefront)?/api-reference(/)?",