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.

Update Product Types and Packaging Types user guides (#14841)

jaburghescb90e0389c1f
diff --git a/docs/images/user/settings/package-types/1-package-types-overview.png b/docs/images/user/settings/package-types/1-package-types-overview.png
new file mode 100644
index 0000000000..fffad00cf6
Binary files /dev/null and b/docs/images/user/settings/package-types/1-package-types-overview.png differ
diff --git a/docs/images/user/settings/package-types/2-add-package-type.png b/docs/images/user/settings/package-types/2-add-package-type.png
new file mode 100644
index 0000000000..73e7f16f60
Binary files /dev/null and b/docs/images/user/settings/package-types/2-add-package-type.png differ
diff --git a/docs/images/user/settings/product-types/1-product-types-overview.png b/docs/images/user/settings/product-types/1-product-types-overview.png
new file mode 100644
index 0000000000..26c8fca2e8
Binary files /dev/null and b/docs/images/user/settings/product-types/1-product-types-overview.png differ
diff --git a/docs/images/user/settings/product-types/2-new-product-type.png b/docs/images/user/settings/product-types/2-new-product-type.png
new file mode 100644
index 0000000000..9bb7abd0ac
Binary files /dev/null and b/docs/images/user/settings/product-types/2-new-product-type.png differ
diff --git a/docs/user/settings/package-types.mdx b/docs/user/settings/package-types.mdx
index f6cc83ab3d..88e5440cc7 100644
--- a/docs/user/settings/package-types.mdx
+++ b/docs/user/settings/package-types.mdx
@@ -1,39 +1,92 @@
---
title: "Package Types"
-description: "The boxes, envelopes, cartons and pallets your goods ship in — with the dimensions and weights carrier quotes are built on."
+description: "Learn how to define the boxes, cartons, pallets and containers your store packs goods into, and how cartons set the case quantities behind bulk orders."
---
-Package types describe what you pack into: the mailer your parcels go out in, the cartons your products come in, the pallets a wholesale order leaves on. Their size and weight feed shipping quotes, so getting them right is what keeps carrier rates honest.
+A package type defines the physical packaging that goods are packed into: a box, an envelope, a carton, a pallet or a container. Each one records its measurements, its empty weight and what it can carry, so the same packaging is described once and referenced wherever it is used.
-Find them under **Settings → Package types**.
+The packaging you need depends heavily on the nature of your business. A store sending single items to consumers may only ever need two or three sizes of box and a padded envelope. A wholesaler selling by the case needs the cartons those cases come in, and the pallets they are stacked on. A business doing both needs each, because an order for one unit and an order for two hundred do not leave the warehouse the same way.
-## Kinds
+To manage packaging, navigate to **Settings → Package types**, under the **Shipping & delivery** group.
-| Kind | Typical use |
+![The Package types list, showing each type's dimensions and volume](/docs/images/user/settings/package-types/1-package-types-overview.png)
+
+Each row shows the **Name**, **Kind**, **Dimensions** and **Volume**, and the default carries a **Default** badge.
+
+## How to Add a Package Type
+
+Click **Add package type**.
+
+![The Add package type panel](/docs/images/user/settings/package-types/2-add-package-type.png)
+
+- **Name** - What your team calls it, such as Small mailer or Euro pallet.
+- **Kind** - What sort of packaging it is. See the table below.
+- **Length**, **Width**, **Height** and **Unit** - The outside measurements of the packaging itself.
+- **Empty weight** and **Unit** - Weight of the packaging itself, added to whatever it holds.
+- **Max weight** - What it can carry.
+- **Default box** - Marks this as the store's default packaging. One default at a time.
+
+Click **Create**.
+
+### Package Kinds
+
+| Kind | What it is |
+|---|---|
+| **Box** | Outer packaging an order is packed into |
+| **Envelope** | Flat or padded packaging for small, light items |
+| **Carton** | The case that holds multiple units of a single product |
+| **Pallet** | The platform cartons are stacked on |
+| **Container** | A shipping container |
+
+**Carton** is the only kind a product points at directly. The rest are records of packaging you hold, named so your team can refer to the same thing by the same name.
+
+### Cartons
+
+Cartons behave differently from other packaging types and are worth understanding separately. Every other kind describes the packaging a shipment travels in. A carton describes the case that holds multiple units of a single product, so it attaches to the product rather than to anything you send.
+
+That might be the case the product arrived in from your supplier, or it might be packaging you make up yourself when picking a bulk order. Either way, what makes it a carton is that it holds a known quantity of one product, which is what lets Spree work out the weight and volume of a bulk order from the number of units on it.
+
+#### Where the figures live
+
+A carton is described in three places, and all three are needed before bulk orders behave properly.
+
+| Where | What it records |
|---|---|
-| Box | A parcel |
-| Envelope | Documents, flat items |
-| Carton | A case of units, as it arrives from a supplier or ships wholesale |
-| Pallet | Many cartons, for freight |
-| Container | A shipping container |
+| **Settings → Package types** | The size of the case itself, its empty weight and what it can carry. Shared by every product packed the same way. |
+| A product's **Packing** section | Which carton this product uses, what one packed carton weighs, and how many go on a pallet. |
+| A product's **B2B ordering** section | How many units are in a carton, and whether buyers order in units or cartons. |
+
+The split exists because the same case can hold very different products. The box is shared; what goes in it, what it weighs full and how many fit on a pallet are not.
+
+<Warning>Filling in one product section without the other leaves the figures incomplete. If **Purchase unit** is **carton**, **Units per carton** must be a positive value before the product can be saved.</Warning>
+
+<Note>The **Packing** section lets you select package types whose kind is Carton. The **B2B ordering** section sets the purchase unit and, for carton purchases, the units per carton. Until you have defined at least one carton type, the **Packing** section on every product is greyed out, with a prompt to come back here and add one.</Note>
+
+#### How many you need
+
+One carton type per distinct case size, not one per product. A case of 24 lipsticks and a case of 12 hair dryers are different sizes, so they are two carton types, each pointed at by however many products share it. Suppliers tend to standardise, so most stores need far fewer carton types than they have products.
+
+<Note>Cartons are one part of selling wholesale, alongside minimum order quantities and order multiples. See [<u>Sell to Businesses</u>](/user/how-to/selling-to-businesses) for how they fit together.</Note>
+
+<Note>**Empty weight** is the packaging on its own, before anything goes in it. It is worth entering, because what a packed case weighs is the goods plus the box, and leaving it out understates the total by the weight of the packaging.</Note>
+
+## Setting the Default
-## Adding one
++Only one package type can be the default for a given marketplace or seller at a time. Turning it on for one takes it off any other default in that same scope. A marketplace default and a seller default can coexist, and the seller default takes precedence for that seller. Make it the packaging you use most, since it is what stands in when nothing more specific applies.
-Click **Add package type** and give it a name, a kind, and its geometry:
+## How to Edit a Package Type
-- **Length, width, height** and their unit. Used for carrier dimensional weight, and for the cubic-metre tiers freight shipping compares.
-- **Empty weight** — the packaging itself, added to whatever it holds.
-- **Max weight** — what it can carry.
+Open the row menu and choose **Edit**.
-## The default box
+Editing a carton corrects every product packed into it at once, so fixing a measurement in one place fixes it everywhere that carton is used.
-Mark one package type as the **default box**. It is the packaging your parcel quotes are built on: its size and empty weight are added to every rate a carrier returns. There is one default at a time; marking another demotes the previous one.
+## How to Delete a Package Type
-## For marketplaces
+Open the row menu and choose **Delete**.
-Sellers keep their own package types in the seller panel, alongside the marketplace's. A seller can pack into the operator's standard cartons rather than measuring them again, or record their own — and each seller has their own default box for their own quotes.
+<Warning>Check which products use a carton before removing it. An in-use carton cannot be deleted until its product references are removed.</Warning>
-## Related
+## Further Reading
-- [Delivery Profiles](/user/settings/delivery-profiles) — the delivery methods that use these dimensions when quoting
-- [Purchase Orders](/user/inventory/purchase-orders) — stock arriving in cartons
+- [<u>Sell to Businesses</u>](/user/how-to/selling-to-businesses) - How cartons fit into wholesale ordering
+- [<u>Create a Product</u>](/user/products/creating-products) - Where a product's carton is set
diff --git a/docs/user/settings/product-types.mdx b/docs/user/settings/product-types.mdx
index 942eb5b8c9..a5091b3365 100644
--- a/docs/user/settings/product-types.mdx
+++ b/docs/user/settings/product-types.mdx
@@ -1,37 +1,73 @@
---
title: "Product Types"
-description: "Templates for the kinds of thing you sell — so a new pair of shoes starts with the right options, categories and fields already in place."
+description: "Learn how to use product types in Spree Commerce to pre-fill new products and control how they can be delivered."
---
-Merchants who sell more than one kind of thing end up repeating themselves. Every pair of shoes needs Size and Colour, belongs under Footwear, and wants a Material field. Every book needs an ISBN and an author.
+A product type is a template for products that share similar characteristics. A T-Shirt type carries the option types every shirt needs, the categories they belong in, the data fields associated with them, and the delivery profile they ship on. Create a product using that type, and all of these will be pre-configured.
-A product type captures that once. Creating a product from a type gives it the right option types, the right categories, the right delivery profile, and a form that asks for the fields that kind of product actually needs.
+Using product types doesn't just save time. It gives every product of a similar nature the same starting point. Left to themselves, one person might add a Size option and another adds Sizing, one fills in the fabric composition and another forgets, and six months later the catalog cannot be filtered or reported on properly because no two products agree on what they carry. A type settles those decisions once, so the twentieth product starts out matching the first, without anybody having to remember or check how the first was set up.
-Find them under **Settings → Product types**.
+That matters most when the catalog is large, or when more than one person adds to it. A product is free to differ from its type afterwards, so a type sets the standard rather than enforcing it. The exception is a custom field marked required, which is checked every time a product of that type is saved.
-## Creating a type
+To manage product types, navigate to **Settings → Product types**, under the **Shipping & delivery** group.
-Click **New product type**, name it — "Footwear", "Books" — and choose what it seeds:
+![The Product types list, showing each type and how many products carry it](/docs/images/user/settings/product-types/1-product-types-overview.png)
-| Setting | What a new product of this type gets |
-|---|---|
-| Option types | Its variant axes, such as Size and Colour |
-| Categories | Where it is filed by default |
-| Delivery profile | How it ships |
-| Custom fields | Which fields its edit form asks for, and which are marked required |
+## How to Create a Product Type
-## A type is a template, not a rule
+Click **Add product type**.
-This is the part that decides how to think about them. A type is applied **when a product is created**. After that, the product is its own record:
+![The New product type panel](/docs/images/user/settings/product-types/2-new-product-type.png)
-- Editing the type later does not change products already made from it. Add an option type to Footwear and existing shoes are untouched.
-- A product can be moved to a different type, or detached from its type, without losing anything.
-- **Required** on a custom field is advice to the person filling in the form, not a rule the server enforces.
+- **Name** - What the type is called, such as T-Shirt.
+- **Option types** - Added to products created with this type. Used to create variants.
+- **Categories** - Added to products created with this type.
+- **Delivery profile** - Stamped onto products created with this type, and what decides the delivery options offered at checkout. Choose **Store default profile**, or a specific [<u>delivery profile</u>](/user/settings/delivery-profiles) for goods that ship differently.
-If you do want to push a type's option types and categories onto the products that already carry it, use **Apply to products**. It previews how many products will change, and only ever *adds* — it never removes what a product already has.
+### Custom fields
-## Related
+At the foot of the panel you can attach [<u>custom fields</u>](/user/settings/custom-fields) to the template, so that every product of this type carries them.
-- [Creating Products](/user/products/creating-products) — choosing a type when a product is created
-- [Product Options](/user/manage-products/product-options) — the option types a product type seeds
-- [Custom Fields](/user/settings/custom-fields) — the field definitions a type can ask for
+Each field you attach can be marked **required**, which means a product of this type cannot be saved until somebody fills it in. That is the difference between hoping a field gets filled and knowing it has been.
+
+Drag the fields into the order you want. That order is the order they appear on the product form, so group them in a way that makes sense rather than leaving them in the order you happened to add them.
+
+<Note>Only custom fields that already exist can be attached here. Create them first in [<u>Custom Fields</u>](/user/settings/custom-fields), making sure to set **Applies to** to Products.</Note>
+
+Click **Create product type**.
+
+<Warning>Most of what a type carries is a starting point rather than a rule. Option types, categories and the delivery profile are copied onto a product as it is created, and the product is free to differ afterwards. Required custom fields are the exception: those are enforced every time the product is saved.</Warning>
+
+## How to Edit a Product Type
+
+Open the row menu and choose **Edit** to change the name, the option types, the categories, the delivery profile, or the custom fields.
+
+### What reaches products that already exist
+
+Editing a type does not rewrite the products already using it. What changes, and for whom, depends on what you edited:
+
+- **Option types and categories** shape products created from now on. Products that already carry the type keep what they have.
+- **The delivery profile** is stamped on at creation, so changing it never moves products that already carry the type.
+- **Custom fields** show on every product of that type immediately, including ones that already exist.
+
+<Warning>Marking a custom field required applies to every product of that type, not only new ones. An existing product missing that value cannot be saved again until somebody fills it in, so add a required field before the catalog is large, or expect to backfill data.</Warning>
+
+### Applying changes to existing products
+
+When you do want a change to reach products that already carry the type, use **Apply to existing products**. The button shows how many products it will affect.
+
+This adds the type's missing option types and categories to those products. Nothing is removed, so a product that has drifted from the template keeps whatever it gained along the way.
+
+<Note>This is additive only. It cannot be used to strip option types or categories from products that should no longer have them.</Note>
+
+## How to Delete a Product Type
+
+Open the row menu and choose **Delete**.
+
+<Warning>A type still used by products cannot be deleted. Move those products onto another type first, or the delete is refused.</Warning>
+
+## Further Reading
+
+- [<u>Delivery Profiles</u>](/user/settings/delivery-profiles) - The profiles a type can stamp onto products
+- [<u>Custom Fields</u>](/user/settings/custom-fields) - Fields that show on every product of a type
+- [<u>Product Options</u>](/user/manage-products/product-options) - The option types a product type carries