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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.mdxindex 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.mdxnew file mode 100644index 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 enddiff --git a/docs/developer/core-concepts/fulfillments.mdx b/docs/developer/core-concepts/fulfillments.mdxindex 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 afirst-class status:-```ruby-# an initializer+```ruby config/initializers/spree.rbSpree::Fulfillment.add_status('in_production', after: 'unfulfilled')```diff --git a/docs/developer/core-concepts/promotions.mdx b/docs/developer/core-concepts/promotions.mdxindex 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.mdxindex 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.mdxindex 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 MyAppend```-Register it in an initializer:+Register it in `config/initializers/spree.rb`:```ruby# config/initializers/spree.rbdiff --git a/docs/developer/how-to/custom-report.mdx b/docs/developer/how-to/custom-report.mdxindex 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.rbRails.application.config.after_initialize dodiff --git a/docs/developer/how-to/custom-stock-splitter.mdx b/docs/developer/how-to/custom-stock-splitter.mdxindex 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.rbRails.application.config.to_prepare dodiff --git a/docs/docs.json b/docs/docs.jsonindex 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.mdxnew file mode 100644index 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