Commerce OS Guide

Chapter 1 — What Commerce OS Gives You

Commerce OS turns the customer portal from a passive view into an active ordering surface. Customers can browse a catalog, place orders, track them, and pay — without you having to type anything in.

What it adds

Default landing path

/console/business/buyers/profiles

Chapter 2 — Roles That Light Up

Chapter 3 — Setting Up the Catalog

The catalog is what customers see when they log in to order. It's built from your Item Master — there's no separate catalog database. You just flip a "visible in catalog" toggle on the SKUs you want orderable.

Walkthrough A — make a SKU orderable

Prerequisites

• Signed in as company_admin.
• The SKU exists in Item Master with weight + dimensions filled in (so the catalog can show shipping estimates).

What the screen looks like

Open /console/business/wms/item-master. Click on the SKU you want to expose. Detail page has tabs: Profile / Barcodes / Pricing / Catalog / Inventory. The Catalog tab is the one to use.

Step-by-step

1. From the SKU detail, click the Catalog tab.
2. The catalog form has these fields:
   • Visible in Catalog — toggle. Off by default. Turn it on.
   • Customer-Facing Display Name — optional. If blank, falls back to Item Master's product name. Use this if internal names are cryptic ("SKU-BLU-TS-MED-V2") and you want customers to see "Blue T-Shirt, Medium".
   • Customer-Facing Description — optional. Marketing copy, fabric notes, etc. Supports multi-line text.
   • Image URL — optional. Upload a product image or paste a URL.
   • Public Price — optional. The price shown to buyers who don't have a contracted rate. Leave blank to hide pricing in the catalog (some 3PLs hide pricing entirely).
   • Currency — defaults to your tenant's currency.
   • Catalog Min Available — number. If on-hand drops below this, the SKU shows as "out of stock" in the catalog. Default 0 (always show).
   • Min Order Qty — number. Buyer can't order fewer than this.
   • Lead Time Days — displayed to buyer as "ships in N days".
3. Click Save Catalog Settings. Toast: "Catalog settings updated."
4. The SKU now appears in /console/customer/catalog for any portal user whose buyer profile allows it.

Walkthrough B — bulk-mark many SKUs as catalog-visible

1. Go to /console/business/sales/catalog.
2. Top-right: click Bulk Edit Catalog.
3. Filter the SKU list (by category, status, etc.) to find the SKUs you want.
4. Tick the checkboxes on the rows. Use "Select all on page" or "Select all matching" for large batches.
5. Click the bulk action bar: Mark Visible / Hide / Set Lead Time.
6. Confirm. Toast shows count: "247 SKUs marked visible."

Walkthrough C — preview the catalog as a customer would see it

1. Go to /console/business/sales/catalog.
2. Top-right: Preview as Customer.
3. Pick a buyer from the dropdown.
4. System opens a new tab showing exactly what that buyer sees at /console/customer/catalog — filtered by their buyer profile, with their pricing.

Chapter 4 — Buyer Profiles

A buyer profile customizes the storefront experience for one downstream customer. One profile per customer.

Walkthrough — create a buyer profile

Prerequisites

• company_admin.
• The customer record already exists in 3PL OS (/console/customer-service/customers).

Step-by-step

1. Go to /console/business/buyers/profiles. Header: "Buyer Profiles". Top-right: Create Profile.
2. Click Create Profile. Modal opens.
3. Fields:
   • Customer → typeahead. Pick the customer this profile is for.
   • Catalog Visibility → radio: All visible SKUs / Subset (specify SKUs) / Hidden (no catalog access).
   • If Subset: SKU Allowlist appears — tag input where you add specific SKUs.
   • Pricing Override → table. Add per-SKU prices that override the public catalog price. Format: SKU + price.
   • Payment Terms → dropdown: Prepaid / Net 7 / Net 14 / Net 30 / Net 60.
   • Default Address → typeahead from the customer's address book; the address shown by default at checkout.
   • Order Approval Required → checkbox. If on, buyer's orders go to your Orders Pending Approval queue before becoming fulfillment orders.
   • Status → Active / Suspended.
4. Click Create. Toast: "Buyer profile created." Profile appears in the list.

Worked example

You've signed Acme Corp on Net 30 terms with a 10% discount on shirts. Steps:

1. Create profile with Customer = Acme Corp.
2. Catalog Visibility = "Subset", add only shirt SKUs to the allowlist.
3. Pricing Override: add 10% discounted prices on each shirt SKU.
4. Payment Terms = Net 30.
5. Default Address = Acme's main warehouse.
6. Order Approval Required = off (you trust them).
7. Save.

Chapter 5 — Walkthrough: Customer Places an Order

From the customer's perspective. This is what your customers will do.

Walkthrough — customer_buyer places a B2B order

Prerequisites (on the customer's side)

• Customer has portal credentials (sent by their company_admin or by you).
• Customer's role is customer_buyer or customer_admin.
• Their buyer profile is active.
• Catalog has visible SKUs for them.

Step-by-step (customer)

1. Customer opens their browser to your tenant URL (e.g., www.trenvar.com/acme-warehouse/login).
2. Signs in. Lands at /console/customer/inventory by default. Sidebar shows: Inventory, Catalog, Orders, Invoices, Integrations.
3. Click Catalog in the sidebar.
4. The catalog screen shows: search bar at top, category filters on the left, product cards in a grid (image, name, price, "ships in N days").
5. Customer browses, finds a product, clicks the card. A detail panel opens showing description, full specs, available quantity, and an "Add to Cart" form.
6. Customer types qty (must be ≥ Min Order Qty). Clicks Add to Cart. A small toast confirms: "Added — 5 × Blue T-Shirt M". The cart icon (top-right) shows a count badge.
7. Customer adds more items as needed. When ready, clicks the cart icon to open the cart page.
8. Cart page shows line items + qty + price + line total + cart total. Customer can edit qtys or remove lines.
9. Click Proceed to Checkout.
10. Checkout page:
    • Ship-To Address → defaults to buyer profile default. Click Edit to pick another saved address or enter a new one.
    • Carrier / Service → optional. Leave on default if you set one in their buyer profile.
    • PO Number → optional reference number from the buyer's procurement system.
    • Notes → free text for the warehouse.
    • Order Summary → subtotal, estimated shipping, estimated tax, total.
11. Click Submit Order.
12. Confirmation page appears: "Order O-20260503-001 received. We'll email you when it ships." Order is also visible at /console/customer/orders with status open.

What happens on your warehouse side

1. Trenvar creates a fulfillment order in /console/business/wms/fulfillment with the buyer as customer and the line items as required lines.
2. If Order Approval Required is off → goes straight to operator's pick queue.
3. If Order Approval Required is on → lands in /console/business/orders/pending-approval; you click Approve or Reject with a reason.
4. Operator picks/packs/ships normally.
5. Customer sees status updates live in their portal.

Chapter 6 — Walkthrough: Ship-Now Wizard (customer_ship_now creates a label)

This is the user-facing example. A customer with the customer_ship_now role just wants to print a shipping label — no order, no fulfillment workflow, just a label. End-to-end walkthrough.

Walkthrough A — admin setup (one-time)

Prerequisites

• company_admin.
• Carrier credentials configured (FedEx / UPS / DHL / USPS / Canada Post — at /console/business/settings/shipping).
• The customer's record exists.
• You're going to invite a portal user with the customer_ship_now role.

Step 1 — invite the customer_ship_now user

1. Go to /console/business/settings/users.
2. Click Add User.
3. Fill:
   • Email → the customer's email.
   • Display Name → the person's name.
   • Role → tick customer_ship_now (or customer_ship_now_prepaid if they pay upfront).
   • Linked Customer → pick their customer record.
4. Click Save. The system sends them an invite email.

Step 2 — pre-load their address book (optional but helpful)

1. Go to the customer record (/console/customer-service/customers/[customerId]).
2. Click the Addresses tab.
3. Click Add Address.
4. Fill: Label ("HQ", "Warehouse #2", "Customer X"), Recipient Name, Phone, Email, full street address, city, state, zip, country.
5. Save. Repeat for any addresses they ship to often.
6. The customer's portal Ship-Now wizard will show these as quick-pick options.

Walkthrough B — customer_ship_now creates a label (the headline flow)

Prerequisites (customer side)

• Customer has accepted their invite + set a password.
• They know their tenant URL.

Step-by-step (customer)

1. Customer opens browser, goes to your tenant URL (e.g., www.trenvar.com/acme-warehouse/login).
2. Signs in. Lands at /console/customer/ship-now (their role's default landing — they don't see other portal screens because the role is restricted).
3. The Ship-Now wizard screen looks like this:
   • Page header: "Ship Now". Below: a 4-step horizontal stepper showing where they are: 1. From & To · 2. Parcel · 3. Service · 4. Confirm.
   • Main area is the current step's form.
4. Step 1 — From & To:
   • Ship From: defaults to your warehouse address (pre-set by you in tenant settings). Read-only for ship_now customers.
   • Ship To: dropdown labelled "Pick from address book or enter new". Saved addresses appear (the ones you pre-loaded). Customer either picks one OR clicks + Enter new address.
   • If new address: fields for Recipient Name, Phone (optional), Email (optional, for tracking emails), Street, City, State/Province, Zip/Postal Code, Country (dropdown).
   • Optionally tick Save to my address book to reuse later.
   • Click Continue to Parcel.
5. Step 2 — Parcel:
   • Number of parcels → defaults to 1. Increase for multi-piece shipments. Each parcel gets its own row below.
   • Per parcel:
     • Weight (kg) — required.
     • Length / Width / Height (cm) — required for most carriers.
     • Carton Type — optional dropdown (small box, medium box, etc.) which auto-fills dimensions.
     • Contents Summary — short text ("Documents", "Apparel", "Electronics"). Carriers use this for customs.
   • Optional: Insurance checkbox + declared value.
   • Click Continue to Service.
6. Step 3 — Service:
   • Trenvar calls each configured carrier's rate API and shows a comparison table:
     • Each row: Carrier logo, Service name (Ground / Express / Overnight), estimated delivery date, price.
     • Sorted by price ascending.
   • Customer clicks the row they want. Selected row highlights.
   • Optional: PO Number / Reference field for their internal tracking.
   • Click Continue to Confirm.
7. Step 4 — Confirm:
   • Summary of From, To, Parcel(s), Carrier & Service, Total Cost.
   • If customer_ship_now_prepaid: a Stripe checkout button. Customer pays first.
   • If customer_ship_now (post-paid): a Generate Label button. The cost is added to their next invoice.
   • Customer clicks the button. Spinner: "Calling carrier..."
8. Within ~10 seconds, the result page shows:
   • "Label created — tracking number 1Z999AA10123456784".
   • Download Label PDF button (and Print button).
   • Tracking Link (carrier's URL).
   • Email Label button — sends a copy to the recipient if they entered an email.
   • Create Another Shipment button — returns to Step 1.
9. Customer clicks Download Label PDF. The PDF has a 4×6" thermal label or 8.5×11" laser layout depending on tenant settings. They print it, stick it on the parcel, hand the parcel to the carrier (drop-off or scheduled pickup).

What happens on your warehouse side

• A shipping label record is created in tenants/{tenantId}/shippingLabels/{labelId} with origin = customer_generated.
• Optionally a tiny fulfillment order is auto-created (so the label appears in your fulfillment list) — toggle in tenant settings.
• The cost is added to the customer's running balance for their next invoice (or marked paid if customer_ship_now_prepaid).
• If your tenant has Shopify integration, the customer can also auto-trigger Ship-Now from a Shopify order.

Worked example — customer Acme ships 2 parcels via FedEx Ground to a New York address

Lisa, customer_ship_now user at Acme:

1. Logs in to www.trenvar.com/acme-warehouse/login at 2:15 PM.
2. Lands on Ship-Now wizard.
3. Step 1: picks "Acme NY Office" from the address book dropdown.
4. Step 2: 2 parcels. P1: 8 kg, 30×30×20 cm, "Documents". P2: 12 kg, 40×30×30 cm, "Apparel".
5. Step 3: rate comparison shows FedEx Ground $42, UPS Ground $44, USPS Priority $48. Lisa picks FedEx Ground.
6. Step 4: confirms. Clicks Generate Label.
7. 10 seconds later: 2 tracking numbers, label PDF.
8. Downloads, prints, sticks labels on cartons, drops them at FedEx.
9. Acme's next invoice will include line "Shipping label — FedEx Ground — $42 — 2026-05-03".

Walkthrough C — admin reviews ship-now activity

1. Go to /console/business/ship-now (admin view).
2. Page shows a table of all ship-now labels created across all customers.
3. Filter by customer, date range, carrier.
4. Click a row to see label detail: parcels, cost, tracking, who created it (which portal user), when.
5. Audit log link in top right shows full history.

Chapter 7 — Walkthrough: Customer Tracks an Order

After placing an order (Chapter 5) or generating a Ship-Now label (Chapter 6), customers track status from the portal. No emails to your team needed.

What the customer sees

1. Customer signs in.
2. Clicks Orders in the sidebar.
3. Page shows their orders as a table: Order Code, Date, Items, Total, Status pill, Actions.
4. Status pill colors: open (gray) → picking (blue) → picked (blue) → packing (blue) → packed (blue) → dispatched (yellow) → delivered (green).
5. Customer clicks an order row to see detail:
   • Header: order code, date, ship-to address, total.
   • Lines: each SKU, qty, price.
   • Status timeline: vertical timeline showing each status with timestamp.
   • Tracking section (once dispatched): carrier, tracking numbers (linked to carrier's tracking page), POD photo (if available).

Status updates that customers see automatically

Chapter 8 — Walkthrough: Customer Self-Pays an Invoice (Stripe)

Customers pay their own invoices via Stripe Checkout — no chasing, no manual posting.

Prerequisites (your side)

• Tenant has a connected Stripe account (configured at /console/business/settings/stripe).
• Customer has an email on file.
• The invoice is in Issued status — drafts can't be paid.

Walkthrough — customer pays

1. Customer signs in.
2. Clicks Invoices in the sidebar. Sees the invoice list.
3. Clicks an issued invoice. Detail page shows: line items, subtotal, tax, total due, due date, large green Pay Now button (top-right).
4. Click Pay Now. New tab opens with Stripe Checkout (Stripe-hosted page).
5. Stripe Checkout shows: invoice number, amount, payment methods (card / Apple Pay / Google Pay if enabled).
6. Customer enters card details (or picks a saved card if they've paid before).
7. Click Pay $X. Spinner. Stripe processes. ~3–5 seconds.
8. Success page on Stripe's side: "Payment received." Stripe redirects back to the invoice detail.
9. Invoice status flips to Paid; the Pay Now button is replaced by a green "Paid on YYYY-MM-DD" badge.

What happens behind the scenes

• Stripe processes the card.
• Stripe POSTs to /api/stripe/webhooks.
• Trenvar matches the charge to the invoice ID.
• Invoice status flips. paidAt timestamp is recorded.
• An email confirmation goes to the customer + your accounting team.

Chapter 9 — Walkthrough: Customer Connects Shopify

Customers with the customer_admin or customer_ship_now role can connect their Shopify store. Their orders flow into your warehouse automatically.

Walkthrough — customer connects Shopify

Prerequisites

• Customer has the customer_admin or customer_ship_now role.
• They own (or are a staff member of) a Shopify store.
• They have admin access to that Shopify store (to approve OAuth scopes).

Step-by-step (customer)

1. Customer signs in. Clicks Integrations in the sidebar.
2. Page shows a list of connectable integrations. Currently: Shopify (more in future).
3. Click Connect Shopify. Modal opens.
4. Field: Shopify Store URL. Customer types yourstore.myshopify.com (no https, no path).
5. Click Continue. New tab opens with Shopify's OAuth approval screen showing the scopes Trenvar requests:
   • read_orders
   • read_products
   • write_fulfillments
   • read_customers
6. Customer clicks Install App on Shopify's screen.
7. Browser returns to Trenvar at /console/customer/integrations. The Shopify integration card now shows status Connected, with the store URL and a last-sync timestamp ("Never synced").
8. Click Sync Now. Trenvar fetches all paid orders since the connection was made.
9. Spinner shows count: "Syncing 47 orders..."
10. Done. Last-sync time updates. Any SKU mismatches show as exceptions on a panel below.

Step-by-step — handling SKU mismatches

When Shopify sends a SKU that doesn't exist in your Item Master, the order can't auto-fulfill.

1. Open the Integrations page on the customer's portal (or admin equivalent at /console/business/integrations).
2. Find the Sync Exceptions panel. Each row: Shopify order ID, Shopify SKU, why it failed.
3. Click a row. Two options:
   • Map to existing SKU — pick one of your Item Master SKUs to use as the resolution. Future orders with this Shopify SKU will auto-map.
   • Create new SKU — opens a quick-create form using the Shopify product data (name, image, weight, dimensions). After save, the SKU exists in Item Master and is used for this and future orders.
4. Once mapped, click Retry sync on the order. The fulfillment order is created.

Step-by-step — what each sync transmits back to Shopify

• Once your operator marks a Shopify-sourced order as dispatched, Trenvar POSTs back to Shopify's fulfillment API with: tracking number, carrier, fulfilled-at timestamp.
• Shopify marks the order as fulfilled and notifies the end-customer (the Shopify shopper).

Chapter 10 — Daily Flow per Role

company_admin's setup work

1. Mark SKUs as catalog-visible.
2. Create buyer profiles for each B2B customer.
3. Set per-buyer pricing/visibility.
4. Invite buyer users with portal roles.

customer_buyer's day

1. Log in to /console/customer/catalog.
2. Browse, add to cart, place order.
3. Track open orders.
4. Pay invoices.

customer_ship_now's day

1. Log in to /console/customer/ship-now.
2. Enter a one-off shipment.
3. Print the label.

Appendix A — Commerce OS Console Paths

Appendix B — Commerce OS Permissions

Required entitlement

• platform_os.commerce_os.enabled = true.
• platform_os.warehouse_os.enabled = true (dependency).

Appendix C — Glossary

Every Commerce-OS-specific term, in plain English.

B2B Storefront — The customer-facing catalog + cart + checkout experience for buyer-role users.

Buyer profile — Per-customer storefront settings: catalog visibility, pricing override, payment terms, default address, status, order approval requirement.

Cart — The customer's in-progress selection of products before checkout. Persists across sessions.

Catalog — The customer-facing list of orderable SKUs. Built from your Item Master with the "Visible in Catalog" flag.

Catalog Min Available — A SKU field. If on-hand drops below this, the SKU shows "out of stock" in the storefront.

Customer-facing Display Name — Optional alternative SKU name shown to buyers (use this if internal names are cryptic).

Customer Catalog — Per-customer SKU layer. Used for catalog visibility filtering and per-customer overrides.

Lead Time Days — How long the buyer waits between order and dispatch. Displayed on the catalog as "ships in N days".

Min Order Qty — Minimum quantity per line a buyer must order for that SKU.

OAuth — The protocol Shopify uses to authenticate the connection between your storefront and Trenvar. Customer approves it once.

Order Approval Required — Buyer-profile flag. If on, customer orders go to your Pending Approval queue before becoming fulfillment orders.

PO Number — Optional reference number the buyer enters at checkout (their internal procurement reference).

Public Price — A SKU's catalog price shown to buyers without a contracted rate.

Ship-Now — A one-shot label-creation wizard for portal users (separate from full order workflow). See the Ship-Now Client Guide for details.

Shopify SKU mapping — When syncing Shopify orders, the link between a Shopify SKU and your Item Master SKU. Mismatches show in Sync Exceptions.

SKU Allowlist — Optional list on a buyer profile restricting catalog visibility to specific SKUs (rather than all visible SKUs).

Stripe Checkout — Stripe's hosted payment page. Customers click Pay Now, Stripe handles card collection.

Sync Exception — A Shopify order that couldn't be auto-imported because a SKU isn't mapped. Resolve by mapping or creating the SKU.

Visible in Catalog — A SKU flag. Off by default. Turn on to expose the SKU in the customer storefront.

End of Commerce OS Guide  ·  v1.0  ·  May 2026