-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Locations documentation #2375
Merged
jhawthorn
merged 4 commits into
solidusio:master
from
benjaminwil:locations_documentation
Jan 2, 2018
Merged
Locations documentation #2375
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
5ff00a3
Add overview document of locations in Solidus
benjaminwil 8e4b3aa
Add article describing Solidus country and states
benjaminwil bec900d
Add article to describe zones in Solidus
benjaminwil d38b0e4
Revise country and states documentation
benjaminwil File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
# Countries and states | ||
|
||
Solidus uses the list of countries and states provided by [Carmen][carmen-repo], | ||
which uses the countries and states available in the [Debian `iso-codes` | ||
package][debian-iso-codes]. Solidus creates new `Spree::Country` and | ||
`Spree::State` objects for each country and state. | ||
|
||
Carmen is generally up-to-date and should provide Solidus with any country or | ||
state you would ever need. | ||
|
||
[carmen-repo]: https://github.com/carmen-ruby/carmen | ||
[debian-iso-codes]: https://packages.debian.org/sid/all/iso-codes | ||
|
||
## Countries | ||
|
||
If a country or state you require is not recognized, you can add it directly | ||
from your Rails console: | ||
|
||
``` | ||
Spree::Country.create!(iso_name:"NEW COUNTRY", name:"New Country", states_required: true) | ||
``` | ||
|
||
Some countries do not need to be divided into states or subregions. For those | ||
countries, the `Spree::Country` object's `states_required` field is set to | ||
`false`. You may wish to change this value for your custom country or any other | ||
country that you ship to. | ||
|
||
## States | ||
|
||
A state is any sub-region of a country, whether that is a province, district, or | ||
territory. If the state you require is not recognized, you can add it directly | ||
from your Rails console: | ||
|
||
``` | ||
Spree::State.create!(name: "New State", country_id: 1) | ||
``` | ||
|
||
The `country_id` should match the country that the state belongs to. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
# Locations | ||
|
||
In order to sell products, your store requires that you have locations set up. | ||
In Solidus, locations are split up into states, countries, and zones. | ||
|
||
| Group | Contain | | ||
|-----------|-----------------------| | ||
| States | | | ||
| Countries | States | | ||
| Zones | Countries _or_ states | | ||
|
||
Both states and countries refer back to the territorial borders you would find | ||
on a map. (For example, the United States contains 50 states and 16 territories; | ||
Canada contains 10 provinces and 3 territories.) | ||
|
||
Zones are more flexible. They can be set up in whatever way serves your store's | ||
business needs. | ||
|
||
## Locations affect shipments and taxation | ||
|
||
Locations are required because they affect how orders are taxed and how shipping | ||
is calculated. | ||
|
||
For example, if your store is located in Arizona, United States, an order from | ||
within Arizona state would be taxed and shipped differently than an order being | ||
shipped to Tokyo, Japan. | ||
|
||
## Zones are your own unique groups of regions | ||
|
||
Zones are used to make logical groups of countries or states that are unique to | ||
your store. Zones allow you to set specific around how shipments and taxes are | ||
handled for customers in specific regions. These rules can be as general or | ||
specific as you need. For example, a country or a state could be included in | ||
multiple zones, or none at all. | ||
|
||
Whenever you create a tax rate or a new shipping method, it must be tied to at | ||
least one zone. For a deeper discussion of zones [see the Zones | ||
article](zones.md). | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
# Zones | ||
|
||
In Solidus, any regions that you ship to are grouped using zones. Zones are | ||
groups of states or groups of countries. Zones might only have one member | ||
area (such as a zone that only consists of the United States). | ||
|
||
Zones allow store administrators to set shipping rules and tax rates for a | ||
specific geographical area. Zones are especially useful for helping you comply | ||
with the tax variations in different regions. | ||
|
||
Administrators can create zones that are either country- or state-based. | ||
|
||
## Zones and taxation | ||
|
||
When you configure tax rates, you must assign each tax rate a zone. This helps | ||
you comply with local taxes for any region that you ship to. | ||
|
||
You can only assign one zone per tax rate. However, if you have to comply with | ||
more complicated tax rules, you can create multiple tax rates for a single zone | ||
in conjunction with special tax categories, taxes with unique start or end | ||
dates, and taxes that require other special calculations. | ||
|
||
### Zones and taxes in the United States | ||
|
||
If you are a U.S.-based company and ship within the United States, taxes vary | ||
from state to state, and many counties and municipalities have their own | ||
additional sales taxes. You should speak to a tax professional about which tax | ||
rules apply to your store. | ||
|
||
You could also automate your U.S. tax rates by using a web service that provides | ||
U.S. tax rates. For example, you could use [Tax Cloud][tax-cloud] and the | ||
[`solidus_tax_cloud`][solidus-tax-cloud] extension. | ||
|
||
<!-- TODO: | ||
For more information about taxation, [see the Taxation guide](/taxation). | ||
--> | ||
|
||
[tax-cloud]: https://taxcloud.net | ||
[solidus-tax-cloud]: https://github.com/solidusio-contrib/solidus_tax_cloud | ||
|
||
## Zones and shipments | ||
|
||
Zones affect the shipping methods available to customers in certain regions. | ||
Shipping methods require at least one zone, but they could include any number of | ||
zones. | ||
|
||
### Shipping methods require a zone | ||
|
||
Shipping methods require a zone. Zones can be as inclusive or exclusive as the | ||
carriers you use for shipments. | ||
|
||
For example, if you only want to allow UPS to ship packages domestically, you | ||
could set its zone your home country only. You could be even more restrictive | ||
and make a state-based zone that only includes a few states that you wish to | ||
ship to. | ||
|
||
No matter what countries or states your zones include, note that each shipping | ||
method requires at least one zone before it can be used. | ||
|
||
### Shipping methods can include multiple zones | ||
|
||
If you use carriers that ship to multiple regions (for example, throughout North | ||
America, Europe, and Africa), you could configure it with multiple zones | ||
enabled. | ||
|
||
This feature is useful in cases when you use multiple carriers that ship to | ||
different regions. For example, if you use USPS to ship to the United States and | ||
Canada, but you use FedEx to ship to the United States and Canada as well as to | ||
Europe and Africa. | ||
|
||
<!-- TODO: | ||
For more information about shipments, [see the Shipments guide](/shipments). | ||
--> | ||
|
||
## Example zone configuration | ||
|
||
*Note that the following example should not be followed for a store in | ||
production. Always speak with a tax professional before determining your tax | ||
rates and shipping fees.* | ||
|
||
In this simplified example, you operate a store that is located within Arizona, | ||
United States. You need to comply with U.S. and Arizona tax laws, and create | ||
zones that define which shipping methods are available for customers from | ||
different regions. Here is some additional context to flesh out the example: | ||
|
||
- You operate the business out of Arizona. | ||
- Your stock is stored and mailed from your warehouse in Arizona. | ||
- You ship to all 50 of the United States and to Canada. | ||
- You offer USPS First-Class as a delivery service for orders being delivered | ||
within Arizona. | ||
- You offer UPS Ground as a delivery service to any of the 48 continental (or | ||
contiguous) U.S. states. | ||
- You offer only FedEx Express as a delivery service to non-contiguous states | ||
(like Alaska and Hawaii) and to Canada. | ||
- You are only required to apply sales tax to orders delivered within Arizona. | ||
(You have determined the Arizona tax rate by using the maximum amount of tax | ||
charged by a county and a municipality state-wide. You charge the maximum | ||
amount on all in-state orders.) | ||
|
||
In the table below, you can see how your store could use zones in conjunction | ||
with the required tax rates and any shipping methods you wish to use: | ||
|
||
| Zone | Description | Tax rate | Available shipping methods | | ||
|-----------------------|---------------------------------------------|----------|---------------------------------------------| | ||
| In-state | Purchases shipped within Arizona (taxable) | 9.9% | FedEx Express, UPS Ground, USPS First-Class | | ||
| Non-contiguous States | Purchases shipped to Alaska or Hawaii | 0 | FedEx Express | | ||
| Contiguous States | Purchases shipped to all other states | 0 | FedEx Express, UPS Ground | | ||
| Canada | Purchases shipped internationally to Canada | 0 | FedEx Express | | ||
|
||
All of the zones in this table would be state-based with the exception of the | ||
"Canada" zone, which you could configure as a country-based zone with a single | ||
country in it. | ||
|
||
While you might choose to use zones differently in your own store, this example | ||
shows how you might want to group different states according to your own | ||
business needs. | ||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For some countries, dividing them up into sub-territories makes no sense. For those cases, we can determine that the
states_required
field on the country is set to false.If we do that, then the subregions for that country are not chosen for addresses.
This makes sense for many European countries and any small country.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a note about this. 👍