<commit_before>h2. Shipping

This section explains how Spree represents shipping options and how it calculates 
expected costs, and shows how you can configure the system with your own shipping 
methods.
After reading it you should know:
* the design used in Spree
* how to specify your shipping structure
* how to configure products for special shipping treatment
* how to capture delivery instructions

endprologue.

h3. Overview

Spree uses a flexible system which allows you to specify a range of shipping 
options for zones, and supports precise calculation of shipping options. A 
key concept is the 'calculator' - a class which _you_ supply to calculate 
the total shipping cost from a shipment (and the products and quantities it 
contains).

h3. Design and functionality

Rather than try to have a prescriptive general design for shipping possibilities, 
Spree uses a flexible system
based on 'calculators' - objects that perform specific computations from
any information accessible from the whole order. Such calculators have a 
name and a "zone":zones.html of applicability. 
The calculators are called in turn to cost up each applicable option.

h4. What the Customer Sees

In the standard system, there is no mention of shipping until the 
checkout phase. After entering a shipping address, the system displays 
all relevant shipping options and their costs for the whole order. 
Only the shipping options whose zones include the _shipping_ address 
are presented. 
The Customer must choose one before proceeding to the next stage. At 
confirmation, the shipping cost has been added to the order total.

NOTE. You can enable collection of extra _shipping instructions_ by setting the option +Spree::Config.set(:shipping_instructions => true)+. This is turned off by default. Such instructions will be shown in an order's shipment admin page. 

h4. What the Orders Administrator Sees

A shipment object is created at checkout time for the order. Initially it 
records just the shipping method and the order it applies to. The administrator
can update the record with actual shipping cost and a tracking code, and 
may also (once only) confirm the despatch. This confirmation causes a 
shipping date to be set as the time of confirmation. 

NOTE. There is little support at present for split shipments. Spree allows representation of multiple shipments for an order but uses only the last in calculations.

h4. Configuration Options

Administrators may create new shipping methods by specifying a descriptive
name, the name of a suitable calculator class, and a zone. Editing of existing
methods is also allowed.
(Recall that administrators can freely create new zones to reflect 
shipping constraints.)

Each product can also set a +ShippingCategory+, as explained below.


h3. Adding New Methods

The main work is to provide a suitable calculator. You can write your own, but there
are some existing ones which might be useful for simple pricing structures.

NOTE. lib/spree/shipping_calculator is dead code now? seems like code in order.rb

h4. The FlatRate extension

This calculator comes with Spree, and returns a fixed rate depending on the setting of 
preference value +Spree::FlatRateShipping::Config[:flat_rate_amount]+.

h4. Other useful extensions

There are a few Spree extensions which provide additional shipping methods, including
special support for the fees for common carriers, or support for bulk orders.
See the "Spree Extension Registry":http://ext.spreecommerce.org for the latest 
information.

h4. Writing your own

Your calculator should accep a shipmend return a cost. Your calculator can look at 
any reachable data, but typically uses the address and order in a shipment, plus 
the information from variants.

h3. Product Configuration

Users can assign products to specific +ShippingCategories+ or include extra information in variants to enable the calculator to determine results.

Each product has an (optional) +ShippingCategory+: this adds product-specific information
to the calculations beyond the standard information from the shipment (which is
destination address, variants and quantities, and possibly some weight and dimension 
information if given for a variant). +ShippingCategory+ is basically a wrapper for
a string. One use is to code up specific rates, eg "Fixed $20" or "Fixed $40", from 
which a calculator could extract imposed prices (and not go through its usual 
calculations).

h4. Variant configuration

Variants can be specified with weight and dimension information. <commit_msg>refined a few points and fixed some typos<commit_after>h2. Shipping

This section explains how Spree represents shipping options and how it calculates 
expected costs, and shows how you can configure the system with your own shipping 
methods.
After reading it you should know:
* the design used in Spree
* how to specify your shipping structure
* how to configure products for special shipping treatment
* how to capture shipping instructions

endprologue.

h3. Overview

Spree uses a flexible system which allows you to specify a range of shipping 
options for zones, and supports precise calculation of shipping options. A 
key concept is the 'calculator' - a class which _you_ supply to calculate 
the total shipping cost from a shipment (and the products and quantities it 
contains).

h3. Design and functionality

Rather than try to have a prescriptive general design for shipping possibilities, 
Spree uses a flexible system
based on 'calculators' - objects that perform specific computations from
any information accessible from the whole order. Such calculators have a 
name and a "zone":zones.html of applicability. 
The calculators are called in turn to cost up each applicable option.

h4. What the Customer Sees

In the standard system, there is no mention of shipping until the 
checkout phase. After entering a shipping address, the system displays 
all relevant shipping options and their costs for the whole order. 
Only the shipping options whose zones include the _shipping_ address 
are presented. 
The Customer must choose one before proceeding to the next stage. At 
confirmation, the shipping cost has been added to the order total.

NOTE. You can enable collection of extra _shipping instructions_ by setting the option +Spree::Config.set(:shipping_instructions => true)+. This is turned off by default. See "Shipping Instructions":#shipping-instructions below.

h4. What the Orders Administrator Sees

A shipment object is created at checkout time for the order. Initially it 
records just the shipping method and the order it applies to. The administrator
can update the record with actual shipping cost and a tracking code, and 
may also (once only) confirm the despatch. This confirmation causes a 
shipping date to be set as the time of confirmation. 

NOTE. There is little support at present for split shipments. Spree allows representation of multiple shipments for an order but uses only the last in calculations.

h4. Configuration Options

Administrators may create new shipping methods by specifying a descriptive
name, the name of a suitable calculator class, and a zone. Editing of existing
methods is also allowed.
(Recall that administrators can freely create new zones to reflect 
shipping constraints.)

Each product can also set a +ShippingCategory+, as explained below.


h3. Adding New Shipping Methods

The main work is to provide a suitable calculator. You can write your own, but there
are some existing ones which might be useful for simple pricing structures.

NOTE. ******** lib/spree/shipping_calculator is dead code now? seems like code in order.rb

h4. The FlatRate extension

This calculator comes with Spree, and returns a fixed rate depending on the setting of 
preference value +Spree::FlatRateShipping::Config[:flat_rate_amount]+.

h4. Other useful extensions

There are a few Spree extensions which provide additional shipping methods, including
special support for the fees for common carriers, or support for bulk orders.
See the "Spree Extension Registry":http://ext.spreecommerce.org for the latest 
information.

h4. Writing your own

Your calculator should accept a shipment and return a cost. Your calculator can look at 
any reachable data, but typically uses the address and order in a shipment, plus 
the information from variants which are contained in the line_items.

h3. Product Configuration

Users can assign products to specific ShippingCategories or include extra information in 
variants to enable the calculator to determine results.

Each product has an (optional) +ShippingCategory+: this adds product-specific information
to the calculations beyond the standard information from the shipment (which is
destination address, variants and quantities, and possibly some weight and dimension 
information if given for a variant). +ShippingCategory+ is basically a wrapper for
a string. One use is to code up specific rates, eg "Fixed $20" or "Fixed $40", from 
which a calculator could extract imposed prices (and not go through its other
calculations).

h4. Variant configuration

Variants can be specified with weight and dimension information. Some shipping method
calculators will use this information if it is present. 

h3. Shipping instructions

The option +Spree::Config[:shipping_instructions]+ controls collection of additional
_shipping instructions_. This is turned off by default. If an order has any shipping
instructions attached, they will be shown in an order's shipment admin page and can
also be edited at that stage. Observe that instructions are currently attached to
the order and not to actual shipments.


{'fraction_non_alphanumeric': 0.03365434399917158, 'fraction_numerical': 0.003417210313762038, 'mean_word_length': 4.708037825059102, 'pattern_counts': {'":': 5, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '642402', 'n_tokens_mistral': 2315, 'n_tokens_neox': 2200, 'n_words': 1422}