Wp-calypso: New user setup: I want to be prepared to ship my things when my first order comes in (Setup shipping)

[jameskoster]

Success criteria: User adds where shipping from, where shipping to, and carriers they want to use in a single step.

• [x] Design due: April 7

Sketch file: https://www.dropbox.com/s/im759etic6r2wad/setup%20shipping.sketch?dl=0

[DanReyLop]

I've playing around with the REST API and thinking about data structures a lot. These designs don't align well with the current WooCommerce Core implementation of Shipping Zones (Rest Of The World zone can't be removed or edited, for example) but that shouldn't stop us. On the other hand, I have a few other questions.

Will it be possible to edit Shipping Zone names? Or will they just have an auto-generated name, like USA, UK & Ireland, Texas 67000...67999?

Will it be possible to edit Shipping Method names? Like Local Pickup at Main Warehouse etc.

Can a Shipping Zone have 2 methods of the same kind? Like 2 Local Pickup methods? I don't know if it makes sense, but it's currently possible in WC Core.

From the mock-ups, I assume that nothing is sent to the server until the Save & Finish button is clicked, and that saves the whole page. In Calypso, though, it's more common to have each "block" save individually (see https://wordpress.com/settings/general). What do y'all think about that? Also, having the Zone be added to the server when the user clicks Add Zone would simplify error handling and validation, specially for our USPS & Canada Post settings (nothing that can't be overcome, for sure).

cc/ @marcinbot @kellychoffman

[kellychoffman]

Will it be possible to edit Shipping Zone names? Or will they just have an auto-generated name, like USA, UK & Ireland, Texas 67000...67999?

They will be generated on setup, but you will be able to edit them.

Will it be possible to edit Shipping Method names? Like Local Pickup at Main Warehouse etc.

The shipping method names won't be editable, they will be selected via a dropdown.

Can a Shipping Zone have 2 methods of the same kind? Like 2 Local Pickup methods? I don't know if it makes sense, but it's currently possible in WC Core.

Yes, it is possible. There is an 'add additional shipping method' button in the designs.

In Calypso, though, it's more common to have each "block" save individually

This has caused problems in that people think they have to save each block individually, which is too confusing.

Also, having the Zone be added to the server when the user clicks Add Zone

There's 2 Add Zone buttons: On the main page and in the modal. Re: the main page: My only concern with that is this: when they add the zone, couldn't that potentially negatively effect a customer checking out at that moment? (This would be more of an example of a store that is already up and running and they decide to ship to a new zone) I would want the saving and applying to only occur when the zone is completely set up. (ie when they click the Add Zone in the modal.)

[DanReyLop]

Yes, it is possible. There is an 'add additional shipping method' button in the designs.

Yeah I saw that button, but just to double check, I'm referring to 2 (or more) shipping methods of the same type in a Shipping Zone. Like having a California shipping Zone with these methods:

• Flat Rate: $15
• Local Pickup (San Francisco warehouse): $5
• Local Pickup (Sacramento warehouse): $0

It's an edge case for sure, but it's important to design the UI & logic. Also, that ties to my other question about customizing the names of the shipping methods, since that's what the users will see in the checkout.

I would want the saving and applying to only occur when the zone is completely set up. (ie when they click the Add Zone in the modal.)

Yeah that's the Add Zone button I was talking about, sorry for the confusion. So, if the Zone is supposed to be saved when the user clicks the Add Zone in the modal, then you can make changes to your store settings without ever clicking the Save & Finish button in the upper-right corner of the screen. Wouldn't you find that a bit confusing? From my point of view, I would expect nothing to be saved until I click the big blue button in the corner of the screen.

[DanReyLop]

^^ Ping @kellychoffman

[jameskoster]

I'm referring to 2 (or more) shipping methods of the same type in a Shipping Zone

This pretty much only applies to the local pickup method, right? There wouldn't be any reason to add two Flat Rates or any other method?

I can't see any issue with multiple local pickup methods in the same zone.

I would expect nothing to be saved until I click the big blue button in the corner of the screen.

I agree with this. If the user attempts to leave a screen with unsaved changes we should alert them.

[DanReyLop]

This pretty much only applies to the local pickup method, right? There wouldn't be any reason to add two Flat Rates or any other method?

I can't see any reason with the built-in methods, but maybe there's some crazy use-case with USPS/CanadaPost or other methods. Not the kind of use cases we are aiming to support, but Calypso shouldn't 💥 if a merchant configures his zones in WP-Admin in a crazy way.

I agree with this. If the user attempts to leave a screen with unsaved changes we should alert them.

👍

[kellychoffman]

Great questions, Danny. Thanks for clarifying. Let's stick with the ability to add multiple local pickups per method, but no others. And everything else that Jay said.

[DanReyLop]

Ok I have a few more notes about the Shipping Zones. Sorry for not voicing them all at once, but I'm only getting to these problems while I advance in the implementation.

The Rest of the World zone is a special case. Its name can't be changed, and it's always the whole world. If you look at the WP-Admin UI, you'll see that you can't remove the zone, change its name, reorder it or edit its locations. In one of the use cases (I want to ship to the whole world except 3 African countries) the ideal flow is to go to the Rest of the World zone and untick some countries.

To be able to do that in Calypso, we would need to do some creative backend stuff (i.e. hacky as hell). Is it OK, for MVP at least, to mirror the WP-Admin UI in that regard? (Don't allow editing locations from Rest of the World). I'll try to squeeze in the "hacky" backend changes, but it can be a rabbit-hole.

Also, the order of Shipping Zones matter. Suppose you have these zones:

• Alabama (Local pickup)
• US (Flat rate: $5)
• America (Flat rate: $20)
• Rest of the world (Flat rate: $50)

In an order from Alabama, you'll only get Local pickup. In an order from Texas, you'll only get Flat rate: $5, and so on. So, order matters, because once the address matches a shipping zone, the next shipping zones aren't tried. We need a way to reorder zones (possibly drag & drop?). Shouldn't be hard to add (cc/ @marcinbot), I think Calypso already has components for that.

[jameskoster]

Ok I have a few more notes about the Shipping Zones. Sorry for not voicing them all at once, but I'm only getting to these problems while I advance in the implementation.

No problem at all, we fully expect stuff like this to come up. Especially with complex features like shipping.

To be able to do that in Calypso, we would need to do some creative backend stuff (i.e. hacky as hell). Is it OK, for MVP at least, to mirror the WP-Admin UI in that regard? (Don't allow editing locations from Rest of the World). I'll try to squeeze in the "hacky" backend changes, but it can be a rabbit-hole.

How "hacky" are we talking? I know for certain that folks find not being able to edit the Rest of the World zone to be very confusing, so ideally we want to offer functionality as designed.

Probably a crazy idea but; in Calypso could we 'hide' the 'official' Rest of the World zone from the interface (so that folks won't be able to add methods to it)? Then add our own custom 'Global' zone which would essentially provide the same thing, but still be editable / re-namable etc. Not sure if that'd be more or less "hacky" than what you have in mind xD

We need a way to reorder zones

Zone re-ordering is another very confusing concept for users which we'd prefer to avoid. We decided that we wanted to do the ordering for them automatically, but honestly didn't dive deeply enough to figure out if it was possible (either technically or conceptually) or not. So bear with me...

As Zones work on a first-match basis, doesn't it make sense for zones with the most specific conditions be always be ordered first, down to the Zones with the loosest conditions? IE a Zone that covers a specific zip code should be ordered first, one which covers a state comes next, then one which covers a country, then a continent and finally the rest of the world.

That was the idea anyway.

Looking back at your example I see the issue. In that case you'd need to order the US Zone _before_ the Alabama Zone, right? But if automatic ordering was a thing (Alabama ordered before US) you'd just need to add the $5 flat rate method to the Alabama Zone as well, right? Assuming that's the case we basically find ourselves in the position of deciding which is best/worst;

• Designing an intuitive interface for Zone re-ordering which clearly explains the concept. Sure we could just do drag/drop but that doesn't explain what's going on at all.
• Going with automatic ordering and forcing users to potentially have duplicate methods across Zones.

I feel like the main drawback to automatic ordering is when local pickup is used. Going back to your example again, if local pickup was just a cheaper flat rate there wouldn't be a problem right? If that's the case maybe zones that _only_ contain a local pickup method also grab methods from the next Zone up in the list?

I'm not comfortable making a decision here. Maybe there are some other technical issues that can help us decide? Or maybe we need some more stories/scenarios to test? I'm going to ping our resident shipping expert @shaunkuschel (Hey Shaun, start reading here please) to see if he has any input as well.

[DanReyLop]

Probably a crazy idea but; in Calypso could we 'hide' the 'official' Rest of the World zone from the interface (so that folks won't be able to add methods to it)? Then add our own custom 'Global' zone which would essentially provide the same thing, but still be editable / re-namable etc. Not sure if that'd be more or less "hacky" than what you have in mind xD

That's more or less what I had in mind, and it's pretty damn hacky. This is gonna become a frequent counter-argument to your designs: "_What happens if the user configures something in WP-Admin, then comes back to Calypso?_" The user could add a shipping method to the "Real" Rest of World zone in WP-Admin, but that zone would be hidden in the Calypso UI. I'll try to implement it but I would honestly leave it out of the very first version.

As Zones work on a first-match basis, doesn't it make sense for zones with the most specific conditions be always be ordered first, down to the Zones with the loosest conditions? IE a Zone that covers a specific zip code should be ordered first, one which covers a state comes next, then one which covers a country, then a continent and finally the rest of the world.

That would work, and it makes a lot of sense that zones would be configured that way. But, there's nothing stopping a merchant to do something crazy like this:

• Zone 1: Alabama & Texas
• Zone 2: Texas & California

Which zonen should go first? I know that's a silly example, but things start to become more confusing when you add ZIP ranges into the mix.

In WP-Admin, a shipping zone can be comprised of multiple continents, countries, states and ZIP ranges. Maybe it would make sense to restrict a zone to one type of location? Like, you can create a zone only with countries, or only with ZIP ranges? Then, it would be feasible to order automatically, and to disallow zones that have common locations (in my previous example, you couldn't select Texas when creating Zone 2).

Maybe we could simplify things a bit if we make some assumptions, like these:

• It only makes sense to add a ZIP range in the context of a country. ZIP: 930* doesn't make sense, but Country: US & ZIP: 930* does.
• It doesn't make sense to add a ZIP range in the context of a continent. Continent: America & ZIP: 930* doesn't make sense.
• It's superflous to add a ZIP range in the context of a state. State: Utah & ZIP: 860* is correct, but it's equivalent to Country: US & ZIP: 860*.
• A ZIP range is always intended to be more specific than a state. You'll always want Country: XX & ZIP: YYY* to be metched before State: ZZ.
• You could want to make a zone with multiple types of locations. For example: Canada or Washington, or Europe and US, but that's a very uncommon setting and we shouldn't try to optimize the UX for those edge cases.

With those assumptions, we could forbid adding a shipping zone that overlaps with another of the same specificity. For example:

• Zone 1: States: Texas & Alabama
• Creating Zone 2: User select States in the US option, and when selecting the individual states, Texas & Alabama are disabled.

That is the only way I can think of for implementing auto-ordering.

[kellychoffman]

That's more or less what I had in mind, and it's pretty damn hacky. This is gonna become a frequent counter-argument to your designs: "What happens if the user configures something in WP-Admin, then comes back to Calypso?" The user could add a shipping method to the "Real" Rest of World zone in WP-Admin, but that zone would be hidden in the Calypso UI. I'll try to implement it but I would honestly leave it out of the very first version.

The "What happens if the user configures something in WP-Admin, then comes back to Calypso?" argument can't continue be a reason we don't improve the UX. The idea is to take the improvements we've done in Calypso and bring it back to wp-admin. Not being able to edit Rest of World is a huge complaint with the current wp-admin implementation of Zones and we really need to figure out how to support editing the Rest of World Zone.

[kellychoffman]

Maybe we could simplify things a bit if we make some assumptions, like these:

This _sounds_ like a solid plan, but I'd like @shaunkuschel to take a look to make sure we aren't missing anything big.

[DanReyLop]

The "What happens if the user configures something in WP-Admin, then comes back to Calypso?" argument can't continue be a reason we don't improve the UX.

Agreed.

The idea is to take the improvements we've done in Calypso and bring it back to wp-admin. Not being able to edit Rest of World is a huge complaint with the current wp-admin implementation of Zones and we really need to figure out how to support editing the Rest of World Zone.

Shouldn't we fix this in WC Core instead? I would agree with you if this was only a WP-Admin UX problem, but it's not. It's also the way WC Core logic works. We can bend some of the rules, but at the end of the day, the Calypso UI is going to update settings in a vanilla WooCommerce backend.

[kellychoffman]

Shouldn't we fix this in WC Core instead? I would agree with you if this was only a WP-Admin UX problem, but it's not. It's also the way WC Core logic works. We can bend some of the rules, but at the end of the day, the Calypso UI is going to update settings in a vanilla WooCommerce backend.

Agree. Asking Proton about it, stand by! :)

[jameskoster]

Ok, after further chats with @kellychoffman and @mikejolley on Slack I think we've arrived at a simple, acceptable approach to the Rest of the World zone issue.

In short, let's leave the behaviour intact (no editing or deleting) but rename the zone to something like 'Locations not covered by your other zones'. Then we'll ensure the design makes it clear that this zone is different to others (less emphasis) and is _optional_.

So going back to the scenario;

I want to ship worldwide except for 4 countries

Instead of wanting to edit the Rest of the World zone, users will instead understand that they need to create a new zone that covers the appropriate countries. It's a couple of extra clicks but makes the overall experience much less confusing.

The nice thing about this solution is that it shouldn't hold us up (changing the zone name in core is hopefully a minor change) or require any hacky behaviour.

Issue opened for core here; https://github.com/woocommerce/woocommerce/issues/15031

[DanReyLop]

The nice thing about this solution is that it shouldn't hold us up (changing the zone name in core is hopefully a minor change) or require any hacky behaviour.

If that's the desired behaviour, we don't even need to wait for the WC Core change. We can detect which zone is the Rest of the World (it has always id=0) and change its title as it's fetched from the server. It's a 1-line change.

[jameskoster]

For sure, makes sense to apply this enhancement to core as well though xD

[DanReyLop]

cc/ @marcinbot @kellychoffman

So, how do we stand in the Shipping Zone Locations UI? I still think that my assumptions in https://github.com/Automattic/wp-calypso/issues/12717#issuecomment-300768761 are somewhat reasonable, I'm gonna take it from there and keep talking.

To sum up, these will be the kinds of location settings that a zone will be able to have in Calypso:

• One or several postcode ranges (examples: 123* and 86000...86999)
• One or several states (examples: California and Utah)
• One or several countries (example: US and Canada)
• One or several continents (example: Europe and Africa)

The shipping zones will be sorted automatically. A continent(s) zone will have less priority than a country zone. A country zone will have less priority than a state(s) zone. A postcode zone will have the highest priority. So, for example:

• Zone 1: postcode: 123*
• Zone 2: state: NY
• Zone 3: country: US
• Zone 4: continent: America
• Zone 0: Rest of the world

In that scenario, an order with ZIP 12345 would match with Zone 1, even though that postcode correspond with the state of NY (and the US, and America).

We will forbid in the UI to select 2 overlapping zones of the same level of priority. So, if you have the zones above and you add a new one, you won't be able to select NY, US, or America.

How I envision the UI:

• Continents & countries dropdown, like the ones on the designs. If the user chooses several countries, then that's it, no more filtering is allowed.
• If he only chooses one country, then a secondary panel shows up, with the following options (radio buttons, or whatever):
  
  
  
  • Ship to the whole country.
  
  
  • Ship only to the following states. This only appears if the country is divided in states. This will be a simple multiselect list.
  
  
  • Ship only to the following postcodes. Instead of doing the Put one per line (like in WP-Admin), maybe we could do better and add a new textfield for every new postcode range the user wants to add. Or maybe only allow for one postcode range.
  
  

These are examples of location settings that will not be valid in Calypso:

• Several countries and states (Canada and Washington).
• Continents and postcodes (America and 123*) (WTF?)
• Postcode without a country (123*)
• Postcode and state (NY and 123*)

If any of the shipping zones is returned from the server with an invalid configuration, that means that the user has been configuring in WP-Admin. In that scenario, we should avoid auto-ordering the shipping zones, and present an UI similar to the one in WP-Admin. That is, a multiselect list with continents, countries and states, and a textarea (or multiple textfields) to put postcode ranges.

What do you folks think about this? The logic is reasonable to implement in a finite amount of time, does the UI side of this make sense?

[kellychoffman]

Continents & countries dropdown, like the ones on the designs. If the user chooses several countries, then that's it, no more filtering is allowed.

I think you should be able to filter down to States, for example if you choose US as a country in a US Shipping Zone.

If he only chooses one country, then a secondary panel shows up, with the following options (radio buttons, or whatever):

Why is this different than Zones with a single country?

I'm not sure the radio button is the best approach. I'll alter the design today so it includes drilling down into states.

These are examples of location settings that will not be valid in Calypso:

Several countries and states (Canada and Washington).
Continents and postcodes (America and 123) (WTF?)
Postcode without a country (123)
Postcode and state (NY and 123*)

Why can't you add US and Canada to a single zone and then choose the whole country of Canada and then edit the US location to only include Washington?

I'm confused about the postcode restrictions. Why is that different than picking US and instead of choosing the states in which you ship to, you define postcodes instead?

Why won't 'Postcode without a country' work?

[kellychoffman]

@DanReyLop @jameskoster: Maybe it makes sense to jump on a call?

[marcinbot]

@DanReyLop

The shipping zones will be sorted automatically.

WP Admin allows to sort the zones manually. I think if they are not manually sorted then they are just ordered by the time they were created. We should probably stick to the same functionality.

How I envision the UI:

• Continents & countries dropdown, like the ones on the designs. If the user chooses several countries, then that's it, no more filtering is allowed.
• If he only chooses one country, then a secondary panel shows up, with the following options

Looks like in WP Admin the only secondary control is the "Limit to specific ZIP/postcodes" text box, and it can be toggled. It should work with multiple regions (countries/continents/states) selected. Or at least the UI allows for such configuration.

@kellychoffman

Why won't 'Postcode without a country' work?

I haven't looked into the details, but different countries have different postcode formats, but I imagine some systems might still use similar formats. If we don't add a parent region then there's a chance that someone could order shipping to a completely different country than intended. Even if my assumption about the postal systems is incorrect, then the postcode wildcards might be a problem.

But it actually looks like WP Admin allows for postcodes without a country

[DanReyLop]

Why won't 'Postcode without a country' work?

Pretty much what Marcin said. A Spanish postcode has exactly the same format as a US one (5 digits), so that would be ambiguous.

I think you should be able to filter down to States, for example if you choose US as a country in a US Shipping Zone.

If you pick a country, you should be able to filter to some states (for example, you pick US and then you narrow it down to California and Utah), but having it in the same component would be confusing, because that "filter down to states" only makes sense when you have picked a single country.

Why can't you add US and Canada to a single zone and then choose the whole country of Canada and then edit the US location to only include Washington?

The whole point of those restrictions is to allow zone auto-ordering. That means, that the user won't have to reorder zones and everything will always work as expected. Say you have these shipping zones:

• US, only ZIP range 123*
• US, only Utah
• US and Canada
• Mexico and Guatemala
• Europe and Asia
• America

It doesn't matter what order the user has edited them in, it's easy to reorder them programatically. They can be ordered from more specific (postcode) to less specific (state, then country/countries, then continent/s). However, if you take these zones:

• US and Utah and ZIP range 123*
• Whashington and Canada
• Europe and US
• Madrid and France

There, it's impossible to automatically order those zones.

Maybe it makes sense to jump on a call?

Let's jump on a call tomorrow morning, today it's getting late for @marcinbot and me :)