Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Document delivery setup and EasyPost, and stop prices rendering as equations

Damian Legawiec191bfe6d5411
diff --git a/docs/developer/core-concepts/calculators.mdx b/docs/developer/core-concepts/calculators.mdx
index 76d2eef4d9..e49e4d55a2 100644
--- a/docs/developer/core-concepts/calculators.mdx
+++ b/docs/developer/core-concepts/calculators.mdx
@@ -5,7 +5,7 @@ description: The small pieces of arithmetic behind delivery charges and promotio
## Overview
-A calculator works out an amount. "Charge $5 per item." "Take 15% off." "Free over $50, otherwise $7."
+A calculator works out an amount. "Charge \$5 per item." "Take 15% off." "Free over \$50, otherwise \$7."
They exist because the rule and the number are different questions. A promotion decides *whether* a discount applies; a calculator decides *how much*. Keeping them apart means a merchant can change "10% off" to "$10 off" without touching the conditions that decide who qualifies.
@@ -47,23 +47,23 @@ Each calculator takes a few settings — the amount, the percentage, the thresho
## Worked examples
<AccordionGroup>
- <Accordion title="Free delivery over $50, otherwise $7">
+ <Accordion title="Free delivery over \$50, otherwise \$7">
**Price sack**, with `minimal_amount: 50`, `discount_amount: 0`, `normal_amount: 7`.
- A $60 basket pays nothing. A $20 basket pays $7.
+ A \$60 basket pays nothing. A \$20 basket pays \$7.
</Accordion>
- <Accordion title="$3 to ship the first item, $1 for each extra">
+ <Accordion title="\$3 to ship the first item, \$1 for each extra">
**Flexi rate**, with `first_item: 3`, `additional_item: 1`.
- Four items cost `$3 + (3 × $1)` = **$6**. Set `max_items` to stop charging beyond a point.
+ Four items cost `$3 + (3 × $1)` = **\$6**. Set `max_items` to stop charging beyond a point.
</Accordion>
<Accordion title="10% off the order">
**Percent of item total**, with `flat_percent: 10`.
- A $31 order gets **$3.10** off.
+ A \$31 order gets **\$3.10** off.
</Accordion>
<Accordion title="Spend more, save more">
- **Tiered percent** — 5% over $100, 10% over $250, 15% over $500.
+ **Tiered percent** — 5% over \$100, 10% over \$250, 15% over \$500.
The order total picks the tier. One promotion covers the whole ladder instead of three competing ones.
</Accordion>
diff --git a/docs/developer/core-concepts/delivery-setup.mdx b/docs/developer/core-concepts/delivery-setup.mdx
new file mode 100644
index 0000000000..e13fa7a767
--- /dev/null
+++ b/docs/developer/core-concepts/delivery-setup.mdx
@@ -0,0 +1,130 @@
+---
+title: Delivery setup
+description: How delivery is configured in Spree — profiles that decide how a product ships, zones that decide where, methods the customer picks, and where rates come from.
+---
+
+## Overview
+
+Four pieces decide what a customer is offered at checkout:
+
+| Piece | Question it answers |
+|---|---|
+| **Delivery profile** | How does this product ship at all? |
+| **Delivery zone** | Where can it go? |
+| **Delivery method** | What does the customer pick? |
+| **Rate provider** | What does it cost? |
+
+A product belongs to one profile. The profile decides which methods are even
+possible, the zone decides where they apply, and the rate provider prices them.
+
+```mermaid
+erDiagram
+ Product }o--|| DeliveryProfile : "ships as"
+ DeliveryProfile ||--o{ DeliveryMethod : "offers"
+ DeliveryProfile ||--o{ DeliveryZone : "reaches"
+ DeliveryProfile ||--o{ DeliveryOriginGroup : "ships from"
+ DeliveryOriginGroup }o--o{ StockLocation : "covers"
+ DeliveryMethod }o--o| DeliveryZone : "limited to"
+
+ DeliveryProfile {
+ string name
+ string type
+ boolean default
+ }
+```
+
+## Delivery profiles
+
+A **delivery profile** is how a product ships. Every product has exactly one,
+and it is required — a new product gets its product type's profile, or the
+store default.
+
+Two kinds ship with Spree:
+
+| Kind | Behaviour |
+|---|---|
+| `DeliveryProfiles::Shipping` | Physical goods. Offers carriers and counters, produces a parcel |
+| `DeliveryProfiles::Digital` | Downloads and entitlements. No address, no carrier, available on payment |
+
+Whether checkout collects a shipping address is decided by the methods on the
+profile rather than the kind, so a shipping profile offering only click-and-
+collect asks for no address either.
+
+This is what lets one order contain a vinyl record and its download without
+special handling in your storefront: the cart splits by profile, so the
+download is ready immediately and the record gets a tracking number. A cart
+holding only digital goods skips the delivery step at checkout entirely.
+
+A profile also decides **where a product ships from**, through its origin
+groups. A group is a named set of stock locations with its own zones and
+methods, so "ships from the EU warehouse" and "ships from the US warehouse"
+can offer different carriers at different prices. With no groups, every
+location qualifies.
+
+That is how a store with a refrigerated warehouse keeps chilled goods from
+being picked at a dry one: order routing only allocates from locations the
+profile covers.
+
+```typescript Admin SDK
+// What profiles the store has
+const profiles = await adminClient.deliveryProfiles.list()
+
+// Ship a product as a download
+await adminClient.products.update('prod_xxx', {
+ delivery_profile_id: 'dp_digital',
+})
+```
+
+<Note>
+Profiles are a template at creation time, not a live binding: changing a
+profile does not rewrite products already assigned to it. Reassign a product
+explicitly when it should ship differently.
+</Note>
+
+## Delivery methods and zones
+
+A **delivery method** is what the customer picks — "Standard", "Express", "Collect in store". A **delivery zone** decides where it's available.
+
+Zones match on country and state, and also on postal code prefixes and ranges, so you can offer same-day delivery to a handful of city postcodes without listing every one:
+
+```typescript Admin SDK
+await adminClient.deliveryZones.create({
+ name: 'London same-day',
+ members: [
+ { member_type: 'postal_code', country_code: 'GB', postal_code_prefix: 'SW1' },
+ { member_type: 'postal_code', country_code: 'GB', postal_code_from: 'EC1A', postal_code_to: 'EC1V' },
+ ],
+})
+```
+
+A zone member is either a whole country, a state, or a postal code prefix or range.
+
+<Note>
+Delivery zones cover delivery only. Tax is handled separately — see [Taxes](/developer/core-concepts/taxes).
+</Note>
+
+### Pricing and rules
+
+Delivery is priced either by a rule you configure in the dashboard — flat rate, per item, price bands — or by asking a carrier for live rates.
+
+Methods can also carry conditions that decide when they're offered at all: free shipping over a certain order value, or heavy items excluded from letter post. These are applied in one place, so both kinds of pricing respect them.
+
+## Rates
+
+A method is priced one of two ways, and the choice is per method:
+
+- **A calculator** you configure — flat rate, per item, price bands. Predictable,
+ no network call, no carrier account. See [calculators](/developer/core-concepts/calculators).
+- **A rate provider** that asks a carrier what this parcel actually costs.
+ See [EasyPost](/integrations/shipping/easypost), or write your own with
+ [custom delivery rate providers](/developer/how-to/custom-delivery-rate-provider).
+
+A carrier-priced method returns one option per service, so a single "Carrier
+rates" method can offer Ground, 2-Day and Overnight as separate choices.
+
+## Related
+
+- [Fulfillments](/developer/core-concepts/fulfillments) — what happens to the parcel afterwards
+- [Calculators](/developer/core-concepts/calculators) — how a price is worked out
+- [EasyPost](/integrations/shipping/easypost) — live carrier rates and labels
+- [Selling digital products](/developer/how-to/sell-digital-products) — the digital profile end to end
diff --git a/docs/developer/core-concepts/fulfillments.mdx b/docs/developer/core-concepts/fulfillments.mdx
index 896538b26c..ea1a11546f 100644
--- a/docs/developer/core-concepts/fulfillments.mdx
+++ b/docs/developer/core-concepts/fulfillments.mdx
@@ -314,33 +314,10 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/f
</CodeGroup>
-## Delivery methods and zones
+## How delivery is set up
-A **delivery method** is what the customer picks — "Standard", "Express", "Collect in store". A **delivery zone** decides where it's available.
-
-Zones match on country and state, and also on postal code prefixes and ranges, so you can offer same-day delivery to a handful of city postcodes without listing every one:
-
-```typescript Admin SDK
-await adminClient.deliveryZones.create({
- name: 'London same-day',
- members: [
- { member_type: 'postal_code', country_code: 'GB', postal_code_prefix: 'SW1' },
- { member_type: 'postal_code', country_code: 'GB', postal_code_from: 'EC1A', postal_code_to: 'EC1V' },
- ],
-})
-```
-
-A zone member is either a whole country, a state, or a postal code prefix or range.
-
-<Note>
-Delivery zones cover delivery only. Tax is handled separately — see [Taxes](/developer/core-concepts/taxes).
-</Note>
-
-### Pricing and rules
-
-Delivery is priced either by a rule you configure in the dashboard — flat rate, per item, price bands — or by asking a carrier for live rates.
-
-Methods can also carry conditions that decide when they're offered at all: free shipping over a certain order value, or heavy items excluded from letter post. These are applied in one place, so both kinds of pricing respect them.
+Which methods a customer is offered, what they cost and where they reach is
+configured separately — see [delivery setup](/developer/core-concepts/delivery-setup).
## Adding your own statuses
@@ -370,8 +347,7 @@ orders render `fulfilled` as "ready for pickup".
by it, reports group by it, or webhooks fire on entering it, make it a
first-class status:
-```ruby
-# an initializer
+```ruby config/initializers/spree.rb
Spree::Fulfillment.add_status('in_production', after: 'unfulfilled')
```
diff --git a/docs/developer/core-concepts/promotions.mdx b/docs/developer/core-concepts/promotions.mdx
index f4a6bf0b0a..4e308536f0 100644
--- a/docs/developer/core-concepts/promotions.mdx
+++ b/docs/developer/core-concepts/promotions.mdx
@@ -119,7 +119,7 @@ A discount on the whole order. The amount is distributed proportionally across t
**Default calculator:** `FlatPercentItemTotal` (percentage off the order). Also available: `FlatRate`, `FlexiRate`, `TieredFlatRate`, `TieredPercent`.
-**Use case:** "10% off your order", "$20 off orders over $100".
+**Use case:** "10% off your order", "\$20 off orders over \$100".
### Item discount (`CreateItemAdjustments`)
@@ -240,7 +240,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/discount_co
</CodeGroup>
-The returned cart already carries the updated discounts and totals. If the cart doesn't qualify yet — say the code needs a $100 minimum and the cart holds $80 — the code stays on the cart and the discount activates on its own the moment the cart qualifies.
+The returned cart already carries the updated discounts and totals. If the cart doesn't qualify yet — say the code needs a \$100 minimum and the cart holds \$80 — the code stays on the cart and the discount activates on its own the moment the cart qualifies.
Automatic promotions need no customer action at all — they are evaluated on every cart change.
diff --git a/docs/developer/how-to/custom-api-authentication.mdx b/docs/developer/how-to/custom-api-authentication.mdx
index ed82898c79..0d439be118 100644
--- a/docs/developer/how-to/custom-api-authentication.mdx
+++ b/docs/developer/how-to/custom-api-authentication.mdx
@@ -144,7 +144,7 @@ end
## Step 2: Register the Strategy
-Add the strategy to a registry in an initializer. **This is the only line that decides which API the provider serves** — `store_authentication_strategies` for customer login, `admin_authentication_strategies` for staff login. Register with both to allow the same provider on either surface. The key you choose here is what clients send as `provider` in the login payload.
+Add the strategy to a registry in `config/initializers/spree.rb`. **This is the only line that decides which API the provider serves** — `store_authentication_strategies` for customer login, `admin_authentication_strategies` for staff login. Register with both to allow the same provider on either surface. The key you choose here is what clients send as `provider` in the login payload.
<CodeGroup>
diff --git a/docs/developer/how-to/custom-document-numbers.mdx b/docs/developer/how-to/custom-document-numbers.mdx
index 61f84857ee..61b491ce43 100644
--- a/docs/developer/how-to/custom-document-numbers.mdx
+++ b/docs/developer/how-to/custom-document-numbers.mdx
@@ -57,7 +57,7 @@ module MyApp
end
```
-Register it in an initializer:
+Register it in `config/initializers/spree.rb`:
```ruby
# config/initializers/spree.rb
diff --git a/docs/developer/how-to/custom-report.mdx b/docs/developer/how-to/custom-report.mdx
index 0045e460cb..a9c4fc3a4d 100644
--- a/docs/developer/how-to/custom-report.mdx
+++ b/docs/developer/how-to/custom-report.mdx
@@ -115,7 +115,7 @@ to_csv
### Step 3: Register the Report
-Add your report to the registry in an initializer:
+Add your report to the registry in `config/initializers/spree.rb`:
```ruby config/initializers/spree.rb
Rails.application.config.after_initialize do
diff --git a/docs/developer/how-to/custom-stock-splitter.mdx b/docs/developer/how-to/custom-stock-splitter.mdx
index cc4d06366f..8be9461a86 100644
--- a/docs/developer/how-to/custom-stock-splitter.mdx
+++ b/docs/developer/how-to/custom-stock-splitter.mdx
@@ -87,7 +87,7 @@ So the splitter's job is "look at each package's contents, decide which contents
### Step 2: Register the Splitter
-Splitters are registered globally on `Rails.application.config.spree.stock_splitters` — every order runs through the full chain. Add yours via an initializer:
+Splitters are registered globally on `Rails.application.config.spree.stock_splitters` — every order runs through the full chain. Add yours in `config/initializers/spree.rb`:
```ruby config/initializers/spree.rb
Rails.application.config.to_prepare do
diff --git a/docs/docs.json b/docs/docs.json
index 01f00c61c6..f0355b3627 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -523,6 +523,7 @@
"group": "Fulfillment",
"pages": [
"developer/core-concepts/fulfillments",
+ "developer/core-concepts/delivery-setup",
"developer/core-concepts/returns-exchanges-claims",
"developer/core-concepts/addresses",
"developer/core-concepts/calculators"
@@ -559,6 +560,7 @@
"group": "Shipping & WMS",
"pages": [
"developer/providers/fulfillment",
+ "integrations/shipping/easypost",
"developer/how-to/custom-delivery-rate-provider"
]
},
@@ -1900,6 +1902,7 @@
"icon": "truck",
"pages": [
"developer/core-concepts/fulfillments",
+ "developer/core-concepts/delivery-setup",
"developer/core-concepts/returns-exchanges-claims",
"developer/core-concepts/addresses",
"developer/core-concepts/calculators"
diff --git a/docs/integrations/shipping/easypost.mdx b/docs/integrations/shipping/easypost.mdx
new file mode 100644
index 0000000000..f29fdcc277
--- /dev/null
+++ b/docs/integrations/shipping/easypost.mdx
@@ -0,0 +1,171 @@
+---
+title: EasyPost
+description: "Set up EasyPost in Spree for live carrier rates at checkout, label purchase and refunds, customs declarations, and carrier tracking updates by webhook."
+---
+
+## Overview
+
+[EasyPost](https://www.easypost.com/) is a multi-carrier shipping API. One
+account reaches USPS, UPS, FedEx, DHL and a hundred or so regional carriers,
+either on EasyPost's own accounts or on rates you have negotiated yourself.
+
+Spree ships an EasyPost provider that does four jobs:
+
+- **Live rates at checkout** — real carrier prices for the actual parcel,
+ instead of a flat rate you maintain by hand
+- **Labels** — bought when a parcel ships, refunded when it does not
+- **Customs** — declarations on international labels, from data on the variant
+- **Tracking** — carrier updates arrive by webhook and move the parcel along
+
+**When to use it:** you ship physical goods with more than one carrier or
+service, or your prices need to reflect weight and distance.
+
+**When the built-in rates are enough:** flat or free delivery, one carrier at
+one price, or digital-only stores.
+
+## Setup
+
+### 1. Add the gem
+
+```ruby Gemfile
+gem 'spree_easypost'
+```
+
+```bash
+bundle install
+```
+
+### 2. Get an API key
+
+Sign up at [easypost.com](https://www.easypost.com/) and copy a key from
+**API Keys** in their dashboard.
+
+EasyPost issues separate **test** and **production** keys, and the key itself
+decides the mode — there is no toggle in Spree. Test keys produce real rates
+and real-looking labels without ever charging you or moving a parcel.
+
+<Warning>
+A production key buys real postage the moment a label is purchased. Use a test
+key (`EZTK…`) anywhere that is not production.
+</Warning>
+
+### 3. Connect it in the dashboard
+
+Go to **Settings → Integrations**, choose **EasyPost**, and paste the API key.
+Saving with **Active** ticked verifies the key against EasyPost before the
+integration is enabled, so a bad key fails immediately rather than at checkout.
+
+| Setting | What it does |
+|---|---|
+| **API key** | Your EasyPost key. Decides test or production mode |
+| **Webhook secret** | Shared secret that signs carrier tracking updates |
+| **Customs signer** | The person at your company taking legal responsibility for declarations |
+| **Customs contents type** | What international parcels usually contain — merchandise, gift, sample, returned goods |
+| **Incoterm** | Who pays duties on arrival. `DAP` bills the recipient, `DDP` bills you |
+
+<Warning>
+Choose `DDP` only if you actually collect duties from the customer at checkout.
+Otherwise the carrier bills you and the margin disappears quietly.
+</Warning>
+
+### 4. Add a delivery method that uses it
+
+Create a delivery method under **Settings → Delivery** and set its rate
+provider to EasyPost. The method now quotes live rates instead of a
+calculator: at checkout each carrier service comes back as its own option, so
+one method can offer Ground, 2-Day and Overnight.
+
+Narrow or rename what customers see with delivery method services — hide the
+services you never use, rename "FEDEX_GROUND" to "Standard", or add a markup.
+
+### 5. Set your origin address
+
+Rates and labels are quoted **from** a stock location, so every location that
+ships needs a complete, real address including a phone number. Carriers verify
+it and refuse anything they cannot find.
+
+<Info>
+A missing phone number or an unverifiable street address is the most common
+reason a first label purchase fails. Spree passes the carrier's own words
+straight back — "Phone is required but missing" names exactly what to fix.
+</Info>
+
+### 6. Receive tracking updates
+
+Carrier updates arrive by webhook. In EasyPost's dashboard add a webhook
+pointing at your store:
+
+```
+https://your-store.com/api/v3/webhooks/fulfillments/<integration_id>
+```
+
+The integration id is shown on the integration's page in Spree. Set a secret
+on the EasyPost webhook and paste the same value into **Webhook secret**.
+
+<Warning>
+Without a webhook secret, Spree refuses every incoming update. That is
+deliberate: an unauthenticated report could mark parcels delivered, and
+delivery is what return windows and the EU withdrawal period count from.
+</Warning>
+
+## Buying labels
+
+Once a fulfillment has a selected rate, buy its postage from the order page or
+through the API. Buying records the tracking number and mints the consignment,
+so nothing is typed by hand.
+
+```typescript Admin SDK
+const label = await adminClient.orders.fulfillments.labels.create('or_xxx', 'ful_xxx')
+
+// Changed your mind before it shipped
+await adminClient.orders.fulfillments.labels.refund('or_xxx', 'ful_xxx', label.id)
+```
+
+The label file is fetched into Spree's own storage right after purchase, so it
+stays printable after EasyPost's link expires or the integration is
+disconnected. What you paid is recorded on the label as merchant accounting
+data and never shown to the customer.
+
+Refunds go back through the account that sold the label, even if the parcel's
+delivery method changed afterwards. USPS settles refunds asynchronously, so a
+label can sit at `refund_requested` until the carrier answers.
+
+See [shipping labels](/developer/core-concepts/fulfillments#shipping-labels)
+for how postage records behave in general.
+
+## Return labels
+
+A return can carry prepaid postage. EasyPost books it in reverse — from the
+customer's address back to the return's stock location — and the customer
+downloads it from the storefront.
+
+```typescript Admin SDK
+await adminClient.orders.returns.labels.create('or_xxx', 'ret_xxx')
+```
+
+## Customs
+
+International labels carry a customs declaration built from the variant's
+`hs_code`, `country_of_origin` and `customs_description`, plus the defaults on
+the integration. Fill those in on any product you ship across a border —
+without them the carrier decides how to classify your goods, and duties follow
+from that classification.
+
+EasyPost declares; it does not estimate. To show duties to a customer before
+they buy, see [duties and fees](/developer/core-concepts/fees).
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| No rates at checkout | Origin address incomplete, or the parcel exceeds carrier limits |
+| "Address not found" | The origin is not a real deliverable address — carriers verify it |
+| "Phone is required but missing" | A stock location with no phone number |
+| Label buy refused naming a service | The quote expired and that service is no longer offered — re-quote |
+| Tracking never updates | Webhook not configured, or its secret does not match |
+
+## Related
+
+- [Fulfillments](/developer/core-concepts/fulfillments) — parcels, consignments and labels
+- [Custom delivery rate provider](/developer/how-to/custom-delivery-rate-provider) — writing your own
+- [Returns](/developer/core-concepts/returns-exchanges-claims) — prepaid return labels