RFC: Allow to choose if address will be stored in user address book or not

[Air-t]

Problem

Making a checkoutComplete or finalizing the draft order saves the shipping and billing address to the user's address book by default.

1. General Assumptions

There should be a way of changing the default behavior of adding addresses to the user's book. Currently, there is no way to decide if addresses will be stored in the user's address book.

The solution for Checkout:

• Add the saveShippingAddress and the saveBillingAddress flags to the CheckoutCreateInput (allow for creating).
• Add saveAddress flag to the checkoutShippingAddressUpdate (allow for updating).
• Add saveAddress flag to the checkoutBillingAddressUpdate (allow for updating).
• Add the save_billing_address and save_shipping_address to the Checkout model.

The solution for Order:

• Add the saveShippingAddress and the saveBillingAddress flags to the DraftOrderInput (allow for creating and updating).
• Add the save_billing_address and save_shipping_address to the Order model.

2. API changes

Mutations

checkoutShippingAddressUpdate(
  ...
  """
  Option to choose if the shipping address will be saved as a shipping address to the user's address book.
  """
  saveAddress: Boolean
)
checkoutBillingAddressUpdate(
  ...
  """
  Option to choose if the billing address will be saved as a shipping address to the user's address book.
  """
  saveAddress: Boolean
)

Inputs

input CheckoutCreateInput @doc(category: "Checkout") {
  ...
  """Option to choose if the shipping address will be saved as a shipping address to the user's address book."""
  saveShippingAddress: Boolean = true

  """Option to choose if the shipping address will be saved as a billing address to the user's address book."""
  saveBillingAddress: Boolean = true
}

input DraftOrderInput @doc(category: "Orders") {
  ...
  """
  Option to choose if the shipping address will be saved as a shipping address to the user's address book.
  """
  saveShippingAddress: Boolean = true

  """
  Option to choose if the billing address will be saved as a shipping address to the user's address book.
  """
  saveBillingAddress: Boolean = true
}

3. Database changes

class Checkout:
    ...
    save_shipping_address = models.BoolField(default=True)
    save_billing_address = models.BoolField(default=True)

class Order:
    ...
    save_shipping_address = models.BoolField(default=True)
    save_billing_address = models.BoolField(default=True)

4. UML diagrams

No response

5. To Do list

• docs are up-to-date
• checkoutCreateInput has new fields saveBillingAddress and saveBillingAddress
• DraftOrderInput has new fields saveBillingAddress and saveBillingAddress
• checkoutShippingAddressUpdate and checkoutBillingAddressUpdate mutations have saveBillingAddress and saveBillingAddress inputs
• add save_billing_address and save_shipping_address to the Checkout model
• add save_billing_address and save_shipping_address to the Order model

No response

6. To Test

Test Case 1:

checkoutCreate mutation with saveShippingAddress and saveBillingAddress allows to choose if the address will be saved to the client's address book.

Preconditions:
The client is logged in.
The client's address book is empty.

Test Steps:

• Invoke checkoutCreate mutation with saveShippingAddress set to true and saveBillingAddress set to false.
• Complete the checkout process using checkoutComplete mutation.
• Verify that the shipping address is saved to the client's address book, but the billing address is not.

Expected Result:

• The shipping address should be stored in the client's address book.
• The billing address should not be stored in the client's address book.

Test Case 2:

checkoutShippingAddressUpdate and checkoutBillingAddressUpdate mutations allow for switching if the address should be saved or not.

Preconditions:
The client is logged in.
The client has previously completed a checkout with a saved shipping address.

Test Steps:

• Invoke checkoutShippingAddressUpdate mutation with saveShippingAddress set to true.
• Invoke checkoutBillingAddressUpdate mutation with saveBillingAddress set to false.
• Complete the checkout process using checkoutComplete mutation.
• Verify that the updated decisions are reflected in the client's address book.

Expected Result:

• The shipping address should be stored in the client's address book.
• The billing address should not be stored in the client's address book.

Test Case 3:

draftOrderCreate mutation with saveShippingAddress and saveBillingAddress allows to choose if the address will be saved to the client's address book.

Preconditions:
The staff is logged in.
The client's address book is empty.

Test Steps:

• Invoke draftOrderCreate mutation with saveShippingAddress set to true and saveBillingAddress set to false.
• Complete the draft order process marking the draft order as paid.
• Verify that the shipping address is saved to the client's address book, but the billing address is not.

Expected Result:

• The shipping address should be stored in the client's address book.
• The billing address should not be stored in the client's address book.

Test Case 4:

draftOrderCreate mutation with saveShippingAddress and saveBillingAddress allows to choose if the address will be saved to the client's address book. Switch the initial options with draftOrderUpdate.

Preconditions:
The staff is logged in.
The client's address book is empty.

Test Steps:

• Invoke draftOrderCreate mutation with saveShippingAddress set to false and saveBillingAddress set to true.
• Invoke draftOrderUpdate mutation with saveShippingAddress set to true and saveBillingAddress set to false.
• Complete the draft order process marking the draft order as paid.
• Verify that the shipping address is saved to the client's address book, but the billing address is not.

Expected Result:

• The shipping address should be stored in the client's address book.
• The billing address should not be stored in the client's address book.

[korycins]

The initial proposition is to extend the AddressInput with boolean flag for example saveAddress. Its default value could be True to maintain the current API behavior. It would give the customer/developer an option to decide if an address should be added or not.

This would mean, that all mutations which use addressInput will also have this flag and in some cases, it would not make sense to have it there. For example, what would happen if I use AccountAddressCreate mutation and provide saveAddress to False? Is it expected and discussed to just ignore it?

The other approach would be to add saveAddress flag to the order/checkout - the logic is that address saving occurs during the finalization process, so is a property of checkout/order

In that case, I would expect two separate flags: for shipping and for billing

[Air-t]

Thanks! The second option seems reasonable. It was assumed that choices may be stored in the privateMetadata of Order and Checkout instances. If you see any other issues please point them out.

[krzysztofwolski]

Is there any other place in the Saleor API where we depend on "special" privateMetadata values? I find this approach less discoverable than explicit attributes.

[korycins]

We should not use privateMetadata here. If we need new fields, let's extend the existing model.

[Air-t]

Ok, we will not use the privateMetadata to store this information. The additional Checkout database fields will be added instead

[krzysztofwolski]

Additionally, a mutation that will switch booleans should also override the previous choice if needed.

Thats the really important part, since preference if address should be saved is done during the checkout process (when setting the address).

[korycins]

It means, that we also need to extend other mutations to give a possibility to update these settings. (Currently only CheckoutCreateInput is listed above)

[krzysztofwolski]

@Air-t To answer the question re adding args to the checkoutComplete mutation. Personally, I'm not a fan.

• it's arguments are related to the payments so far, not the address logic
• don't like it from DX point of view too:
  • I'm asking the user for "save the address" in the address section
  • I have to keep the answer "somewhere'
  • when I call checkoutComplete (could be a separate view, could even be done in the external app asynchronously!) I have to access "somewhere" to get this value and pass. Not saying it's impossible, but keeping boolean values in the checkout wins by a mile and won't require changes in other part of the system

[szczecha]

What is the expected API behavior if someone passes the saveShippingAddress or saveBillingAddress flag in an anonymous checkout? I don't think someone will want to use the API this way but want to know if then these fields will be skipped or an error will be returned.

[krzysztofwolski]

Good point. IMO the flag could be ignored for the anonymous checkouts.
@Air-t One more thing will require checking:

• customer can create anonymous checkouts and pay for them
• when the account is created with the same email, anonymous orders related to the email are assigned to the account
• I am not aware if this process has impact on customer address book (if the addresses are added to it automatically during such process)

[szczecha]

@krzysztofwolski Ahh, I forgot about this function 😄
Until now, the addresses from these checkouts were not saved in the address book

[szczecha]

I would say not expand it now and if someone ever comes to the need to save addresses in this case, we will consider it.

[krzysztofwolski]

Totally agree, don't think "imported" orders should add anything to the address book, so the current behavior can stay.

[Air-t]

ok so for this implementation we can ignore these cases and adjust in the future if needed

[szczecha]

I think we should also test this feature along with validationRules (CheckoutAddressValidationRules):

So when checkout input will look like this:

mutation {
  checkoutCreate(
    input: {
      channel: "default-channel"
      email: "customer@example.com"
      lines: [{ quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6Mjk3" }]
      shippingAddress: { country: US }
      billingAddress: { postalCode: "XX-YYY", country: US }
      validationRules: {
        shippingAddress: { checkRequiredFields: false }
        billingAddress: { checkRequiredFields: false, checkFieldsFormat: false }
      }
      saveShippingAddress: true
      saveBillingAddress: true 
    }
  ) {
    checkout {
      id
    }
    errors {
      field
      code
    }
  }
}

Addresses should be saved after completing the checkout.