> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Physical products

> Sell items you ship yourself, with flat-rate shipping zones and tracking.

A **Physical** product is an item you pack and send yourself. At checkout the buyer enters a shipping address, Shoppex adds the shipping price of their zone to the order, and after payment the order waits for you. You mark it shipped, optionally with a tracking code, and later mark it delivered.

Shoppex does not print labels or talk to carriers. You ship with the carrier you already use and paste the tracking into the order.

## Setup

<Steps>
  <Step title="Add a shipping zone">
    Open **Settings → Shipping** (`/settings/shop/shipping`) and click **Add Zone**. A zone has:

    * **Zone Name**, for example `Europe`. Buyers do not see it on the checkout page.
    * **Currency** the price is set in.
    * **Shipping Price**, a flat amount per order. `0` makes shipping free for the zone.
    * **Free From**, optional. When the order value reaches this amount, shipping is free. Leave it empty to always charge the price.
    * **Countries** the zone covers.

    Add one zone for each price you charge. Buyers can only order physical products when their country is in a zone.
  </Step>

  <Step title="Create the product">
    Create a product and, under **Delivery & Stock → What Buyers Get**, pick **Physical**. Price, variants, stock, and quantity limits work as they do for a [Service](/selling/products#service) product. If your shop has no shipping zone yet, the editor warns you that buyers cannot order the product.
  </Step>

  <Step title="Sell it">
    The product shows in your storefront like any other product. Buyers add it to the cart and pay through hosted checkout.
  </Step>
</Steps>

## Shipping zones

One zone is one flat price for a group of countries. The rules:

* **One zone per country.** A country can be in only one of your zones. If you add a country that is already in another zone, Shoppex names that zone and refuses the save. Remove the country there first.
* **One charge per order.** The price is charged once per order, not per item and not per product. An order with three physical items pays the zone price once.
* **Free From compares the goods, after discounts.** Shoppex compares the order value after coupons and quantity discounts with the threshold. Tips and payment fees do not count toward it. The threshold is in the zone currency; an order in another currency is converted at the current rate first.
* **Coupons do not discount shipping.** A coupon lowers the goods value only. If it drops the order below **Free From**, shipping is charged again.
* **Up to 100 zones** per shop.

Zone prices are converted into the buyer's checkout currency at the current rate, like product prices.

### Editing and deleting zones

A change to a zone applies to new checkouts. An order the buyer already paid keeps the shipping price it was charged. An unpaid order is priced again with the current zone when the buyer continues the checkout, for example when they pick a payment method.

When you delete a zone, buyers in its countries can no longer order physical products until another zone covers them.

## What the buyer sees at checkout

When the cart has at least one physical item, hosted checkout shows a **Shipping address** step before payment:

* **Country**. The list offers only the countries in your zones.
* **Full name**, **Address**, and **City** are required.
* **Apartment, suite, etc.**, **Postal code**, **State or region**, and **Phone** are optional.

After the buyer saves the address, the order summary shows a **Shipping** line with the zone price, or **Free** when **Free From** applies. The buyer cannot choose a payment method until the address is saved and its country is in one of your zones.

<Note>
  The buyer can change the address until a payment arrives. After that, the address is locked, and the buyer has to contact you to change it.
</Note>

A cart can mix digital and physical products. Digital items are delivered at payment as usual. Only the physical items wait for you.

If your shop has no shipping zone at all, checkout refuses the order right away with "This shop does not ship physical products yet."

## Shipping an order

A paid order with physical items shows a **Ship This Order** strip on the order page, and a **Shipping** card with the full address, the phone number, the zone, and the shipment status.

<Steps>
  <Step title="Mark it shipped">
    Click **Mark Shipped**. Optionally add a **Tracking Code** and a **Tracking Link** (it must start with `https://` or `http://`). Leave **Notify customer by email** on to send the buyer a shipping email.
  </Step>

  <Step title="Correct the tracking if needed">
    After shipping, **Edit Tracking** replaces the tracking code and link. The shipped date stays the same. With **Notify customer by email** on, the buyer gets the new tracking.
  </Step>

  <Step title="Mark it delivered">
    When the parcel arrives, click **Mark Delivered**. The physical items count as delivered and the order leaves your open tasks.
  </Step>
</Steps>

One shipment covers every physical item in the order. You cannot ship part of an order in V1.

Shipping and delivering need the order-fulfillment permission. Shipping zones need the product permissions.

### What the buyer sees after payment

On the checkout completion page and in the customer portal, the buyer sees the shipment state:

| State | Buyer sees |
| - | - |
| Paid, not shipped | "Preparing your shipment" |
| Shipped | "Shipped", with the tracking code and a **Track package** link when you added them |
| Delivered | "Delivered" |

The customer portal also shows the full shipping address. The public order link that anyone with the URL can open shows only the city and country.

## Emails

The **Shipping Confirmation** email tells the buyer that the order is on its way, with the tracking code, the tracking link, and the shipping address. Shoppex sends it when you mark the order shipped with **Notify customer by email** on.

* You decide per shipment: the email goes out when **Notify customer by email** is on (`notify_customer` in the Developer API), even if the **Payment Received** switch on **Buyer Emails** is off. A buyer who opted out of order emails does not get it.
* Shoppex sends one email per tracking. Saving the same tracking again sends nothing; changing it sends an update with its own subject ("Tracking updated for your order").
* Edit the text under **Store → Emails** (`/store/emails`); [Email templates and variables](/selling/email-templates) explains how. The template has the variables `{{shop_name}}`, `{{invoice_id}}`, `{{invoice_url}}`, `{{customer_email}}`, `{{tracking_code}}`, `{{tracking_url}}`, `{{shipping_address}}`, and `{{tracking_updated}}` (`true` when the email announces changed tracking). The buyer's address and the tracking are HTML-escaped in your template, line breaks in the address become `<br>`, and a missing tracking code shows as a dash.
* The default template's button opens the order page, which shows the tracking link when there is one. If you link `{{tracking_url}}` directly, keep in mind it is empty when you ship without a tracking link.

There is no separate "delivered" email.

## Refunds

Shipping is part of the order total, so a full refund includes it. There is no separate shipping refund.

If you refund one physical item of an order with several physical items, the order can no longer be marked shipped or delivered, because one shipment always covers every physical item. Ship the rest outside Shoppex and keep the conversation in the order thread.

## Limits

* **Flat rate only.** There are no weight-based, quantity-based, or carrier-calculated rates, and one rate per zone (no standard and express choice).
* **No labels, no carrier integration.** Shoppex does not buy postage or read tracking status from carriers. You mark shipped and delivered yourself.
* **One zone per country**, up to **100 zones** per shop.
* **One shipment per order.** No partial shipments.
* **No tax on shipping.**
* **Hosted checkout only.** Physical products cannot be sold through subscriptions, the [reseller program](/customers/resellers), gift orders, POS, invoices you create in the dashboard, or orders created through the Developer API. Those paths refuse a physical product instead of skipping the address.

## Developer API and webhooks

Everything above is also available to your own systems:

* Manage zones with the `/dev/v1/shipping-zones` endpoints (`products.read` / `products.write` scopes).
* Ship and deliver with `POST /dev/v1/orders/{id}/ship` and `POST /dev/v1/orders/{id}/deliver`.
* Listen to `order:shipped` and `order:item.delivered`.

See [Asynchronous and manual fulfillment](/developers/fulfillment#physical-products) for the request and response shapes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.