Commerce Operations
Prepare catalog, customer, order, fulfillment, shipping, and support ownership.
Use this page when the workspace will sell products, manage customers, or support orders after launch.
Commerce Setup
Prepare catalog
Create real products, options, categories, and images before inviting teams to operate the workspace. Open Import products from the products list header.
Assign order ownership
Name who handles order review, fulfillment, returns, refunds, and customer support.
Confirm shipping and discounts
Review shipping policy ownership and decide who can create or retire discounts.
Connect support habits
Make sure customer account, order, and return questions have a clear support path.
Before customer checkout, review the required Commerce payment connection check and assign a selectable provider to every active market.
Operating Ownership
| Workflow | Owner | Before launch |
|---|---|---|
| catalog | merchandising owner | products and sellable options exist |
| orders | operations owner | order review and fulfillment path is assigned |
| shipping | logistics owner | default shipping policy is confirmed |
| discounts | commerce owner | promotion approval is clear |
| customers | support owner | account recovery and service expectations are assigned |
When search or filters return no results
When a search or filter leaves a list empty, select Clear filters below the empty results. This clears the search, summary chips, and filter panel conditions and returns to page 1. Your selected Workspace, sort order, page size, and columns stay the same.
Shipping rates
Set shipping fees in the Shipping rates rows of a shipping policy. Each row takes a rate name, rate type, condition, and amount. Base amount and Free shipping minimum are read-only. A policy created in the Admin Panel with no rate rows charges 0 for shipping.
If Shipping rates is not shown on the shipping policy screen, a tenant-admin turns it on:
- Open Settings → Workspace → Fields → Field visibility.
- In Shipping Policies, select Shipping rates and save.
Field hiding affects the Admin Panel only; stored rates and shipping calculation stay the same.
Customer order statistics
Customer Total Order Count includes pending orders. Canceled, fully refunded, returned, test and trashed orders are excluded. First Order At and Last Order At use the earliest and latest createdAt among the contributing orders.
Lifetime Value uses the original totalAmount of those orders; a partial refund does not reduce it. The server-only customer document returns a nullable number according to the contributing orders' currencies.
| Contributing orders | lifetimeValue |
|---|---|
| No orders | 0 |
| One currency with a recognized code and a minor-unit exponent | Sum of the original order totals |
| Multiple currencies | null |
| Missing currency | null |
| Code absent from the currency registry | null |
| Currency without a minor-unit exponent | null |
The Admin Panel displays a separate total for each currency and labels unsupported currencies explicitly. Bounded results carry a capped marker. Each amount stays in its recorded currency.
These read-only values are recalculated when an order is created or its contribution changes, including trash, restore, amount, creation date and customer reassignment. Reassignment updates both customers. These values are not net revenue or accounting measures.
Product Editing Roles
tenant-admin and tenant-editor can create products and edit their text, prices, options, and variants in the active workspace. tenant-viewer cannot save changes. Deleting a product requires tenant-admin (or platform super-admin). Saving a product does not grant access to another workspace.
On a read-only variant detail, existing option values remain visible but cannot be selected or cleared.
When saving partial product changes in the Admin Panel, the save request returns 404 not_found when the product is unavailable in the selected workspace. A variant update or deletion referencing an ID outside that product returns 400 bad_request. Check the workspace, product, and variant IDs before resubmitting; these denials are not temporary server errors.
Customer Group Purchase Eligibility
With Customers enabled, set Organization & selling → Eligible customer groups on a product. Empty means anyone may purchase; otherwise a signed-in customer must currently qualify for at least one selected group to add it, increase quantity, or create a Checkout. Quantity decreases and removal remain available. This is separate from group discounts and does not change listing or detail visibility. unlisted alone does not restrict purchases.
Checkout creation makes the final decision. Membership expiry or revoked group qualification before that point denies purchase. An existing Checkout may continue payment after later policy or group changes. Clear the groups when opening an early-access sale to everyone.
Server purchases also require a Customer-bound Cart and both the Secret Key and that Customer's customerToken delegation. A server credential or body Customer ID alone does not prove qualification. Denial uses product_not_eligible. This gate applies to shopper Cart/Checkout operations; direct merchant Orders, DraftOrder completion, and Order edits retain their existing operator authority.
Cumulative quantity per customer
Set a positive integer in Organization & selling → Max quantity per customer (maxQuantityPerCustomer). This requires Customers and a verified signed-in buyer; leaving it empty preserves existing behavior. All variants share one limit over committed Orders and open Checkouts. Checkout creation makes the final concurrent-purchase decision. Overflow returns 409 purchase_limit_exceeded with details.productId, maxQuantityPerCustomer, and remainingQuantity; guests receive 403 product_not_eligible.
Cancellation and unpaid expiration release all quantity; completed Returns release only their completed quantity. Amount-only refunds and incomplete Returns release none. Unknown payment outcomes stay counted past TTL. Merchant direct Orders, DraftOrder completion, and quantity additions remain audited exceptions whose quantities count afterward. Late payment capture and concurrent merchant overrides may exceed the limit.
For paid admission, the product limit spans every occurrence and admission type sharing its variants; it is not a per-occurrence ticket limit. Server purchases require both the Secret Key and the same Customer's customerToken delegation.
An occurrence-cancellation refund alone does not restore the purchase allowance. Fully refunded Orders and partially refunded Orders that are neither delivered nor purchase-confirmed at Return time have no cancellation or Return release path. A partially refunded Order that is delivered or purchase-confirmed at Return time can restore only its returned quantity by completing a Return with an additional positive refund within the remaining refundable amount. A zero-amount refund cannot complete a Return. Operators can raise the cap or use a separate product; a dedicated allowance-release operation is follow-up work.
Product Changes During Save
If you edit an option or variant while a product is saving, those later edits remain visible as unsaved changes. Record them before choosing Open saved product, then review the saved product and reapply them. Save is blocked while the editor requires this review. A save with no later edit still completes normally.
Product Listing Update Warning
If a save reports that the product was saved but its listing update could not be confirmed, your product changes are saved. The price or availability shown in product lists may still be out of date. Review the saved product and contact the catalog owner if the listing remains incorrect; do not recreate the product. Reloading the editor alone does not confirm that the listing has been updated.
Selling zero-priced products
To sell a variant for zero, add a fixed price row for its market (marketPrices[]) in the Admin Panel's standard variant editor and save the price as 0. You can also save the same row through the server product upsert API. A base price of 0, or a price calculated as 0 through exchange rates, adjustments, or rounding, causes cart requests to return missing_price_row.
The variant list is absent from the sidebar; use Cmd+K search or open /collections/product-variants in the Admin Panel. The Product Editor has no fields for editing fixed market prices.
Shipping policies still apply to shippable products. Any remaining shipping fee is payable through the payment window; a final total of 0 places a paid order without a payment window. Inventory and customer purchase quantity limits also apply to free orders.
For zero-priced product orders paid only for shipping, complete an approved return in the Admin Panel to refund the initial shipping fee.
Zero-total orders without a payment transaction currently do not support ordinary order cancellation or return completion. Agree on cancellation and return handling with the operations owner before selling to customers.
Product List Price and Stock Columns
The product list Price column shows the base price range (lowest to highest) of active variants in the workspace base currency. Market fixed and converted prices are not reflected. It shows "—" when no active variant has a price and "Currency unavailable" when the base currency cannot be confirmed.
Stock is the total Available stock (on hand − reserved, floored at 0 per variant) of active variants that track inventory. A second line shows the active variant count and how many are untracked (unlimited); when every active variant is unlimited the column shows "Untracked". Backorder settings do not change the number. The custom fields column is no longer a default column; add it back from the Columns menu.
In the variant list, the Stock cell shows available stock and inventory status together. Choose additional columns from the Columns menu. Your saved column settings are preserved.
Bulk Order Cancellation
If a bulk cancellation request fails, or returns failures without any successful cancellation, the confirmation retains your reason and displays the error. Retry only after reviewing it. When at least one cancellation succeeds, the confirmation closes and refreshes the list even if some orders failed; review the success, skipped, and failure summaries before selecting any remaining orders again.
Product Order History
Open Order history on a saved product or variant detail in the Admin Panel to inspect order lines in the active workspace. Available to tenant-admin, tenant-editor, and tenant-viewer, the product view covers all its variants; the variant view covers only that variant. Select an order number to open its detail.
Failure messages distinguish invalid search criteria, a missing product or variant, temporary unavailability, and a failed request. Try again appears only for temporary unavailability or a failed request and repeats the same search criteria. Resolve input, target, access, sign-in, or workspace issues as directed before searching again. After changing dates, select Search to apply the new criteria.
The default range is the last 30 days including today in the workspace timezone. Choose start and end dates and select Search to filter by order placement (placedAt), from the start day's midnight inclusive to the day after the end date exclusive. Supported years are 0101–9998, validated consistently in the view and on the server. Order creation time appears separately. Test, deleted, and unplaced orders and deleted order lines are excluded. Original purchase snapshots from canceled or refunded orders remain included.
If a chosen range has no order lines, select Reset to last 30 days to search the default range again. Order, payment, fulfillment, and return statuses appear as individual badges, with summary rows for counts, quantities, and amounts per currency. On narrow screens, scroll the order history table horizontally to inspect the remaining columns.
Rows show the customer name at purchase, variant, SKU, options, purchased quantity, and gross and discounted line values. Order status uses common processing labels without asserting shipping: the product-filtered lines do not establish the shipping mode of an entire mixed order. Amounts display stored totalPrice and discountedTotalPrice without recalculation, including older discounted amounts saved as zero. Currency comes from the line snapshot, falling back to the parent order when absent. Unknown or contradictory currency displays as ? and is excluded from amount totals. Missing amounts display as — and make the corresponding currency total unavailable.
The view loads at most 500 matching lines, newest by line creation, with 25 per page. Order counts, quantities, and totals per currency cover only loaded lines; a partial-result notice appears when more than 500 match. Narrow the date range to inspect more. There is no currency conversion or combined mixed-currency total. Discounted values are not net sales or accounting figures after refunds, returns, order edits, or shipping.
Shipping and Non-Shipping Products
Physical variants should keep requiresShipping enabled so paid orders create carrier fulfillment work. Digital goods, remote classes, services, and other non-shipping variants can disable shipping; those lines do not require a shipping address or shipping fee, do not appear in carrier file export/import, and are skipped by shipment item selection.
Storefront cart responses include each line's shipping requirement so checkout can stay contextual. Non-shipping-only carts skip the shipping address step and shipping summary line; mixed carts still collect shipping for the physical lines.
Mixed orders keep the two paths separate: ship the physical lines through fulfillment orders and carrier tracking, then complete any non-shipping access or service lines through the manual completion flow. Refund and return handling should distinguish physical delivery from digital/service access so shipping refunds and return shipping fees are only used when outbound or return shipping actually applies.
If manual completion processes shipping but physical quantities remain, the result reports a failure and preserves the existing completion state of non-shipping lines. Check the remaining shipping quantity before completing those lines. If the order state has changed, check its latest state before trying again.
After a partial shipment, use Ship remaining quantity in order detail when an in-progress fulfillment order still has physical items to ship. List exports include only that remaining quantity. If the same item spans multiple fulfillment orders and file import cannot safely select its remainder, that row directs you to order detail. Completed, held, or canceled fulfillment work is not reopened; check the current order state and remaining quantity before another shipment.
Return Requests
The return detail shows the cancellation reason, reason detail, canceled time, and actor only for canceled returns. Selecting a reason in the return cancellation action follows the same procedure.
After a return item is created, its order item, product and variant snapshots, quantity, restock action, and restocking fee cannot be changed.
The server refuses a new admission Return when retained occurrence or registration cancellation-refund evidence names the line, or an attributable registration is inactive or inconsistent. If no attributable registration is found, a full Return remains supported when the server verifies its original checkout and hold lineage and no cancellation-refund requirement names that line. This readback does not prove that a registration was never created.
In Commerce Config → Return Policy, eligible shipping-refund reasons appear when the refund mode is Full order return only. Override Note Required appears when Manual Override Allowed is enabled. Clearing the refund mode uses the default Full order return only, so eligible reasons remain visible. Hidden values are preserved when you save and reappear when you enable the parent setting again.
In Console, create return requests from an eligible delivered or confirmed order. Operators select the return lines explicitly, review ordered, already-returned, and remaining quantities, enter per-line restocking fees and a return shipping fee, then submit the net refund amount shown by the breakdown.
The return request records the selected line quantities, returnShippingFee, restockingFee, initialShippingRefundAmount, and refundAmount. initialShippingRefundAmount is the initial outbound shipping refunded to the customer. returnShippingFee is a return-shipping deduction charged to the customer. The net refund is:
refundAmount = sum(lineRefund) + initialShippingRefundAmount - sum(restockingFee) - returnShippingFeeThe initial shipping refund suggestion uses the order-time return shipping refund policy snapshot. Across non-rejected returns, the cumulative initial shipping refund is capped by the order shipping amount. Legacy orders without that snapshot use the order shipping amount as a manual cap and require an audit note for any positive initial shipping refund.
Transaction amounts, payment-provider details, confirmation evidence, and metadata are recorded by the server. Direct collection writes cannot set or change them. The order's Related → Transactions section is for inspecting existing records; use the supported payment and refund flows to record payment activity.
Manual Orders (Draft Orders)
To create a manual order, choose New draft order in the orders list header. Return to open drafts from the link above the orders table. Calculation and completion keep their existing administrator permissions. super-admin also retains the default order creation button in the list.
A workspace with no orders shows guidance explaining where storefront orders appear. With creation permission, use New draft order in the header for phone or direct sales. The open drafts link remains available. Applying search or filters shows the results for those conditions.
The open drafts link and the Draft Orders breadcrumb in the composer open a list filtered to drafts still being written. The composer shows the draft name and its current status. Completed, finalized, and discarded drafts show a summary in place of edit inputs. For completed or finalized drafts, View order appears when you have permission to read the linked order.
Sales that do not go through storefront checkout — phone orders, B2B or manual sales, support-assisted reorders, and quote-before-confirm — are handled as draft orders. In the Console an operator builds a draft with line items, a customer or customer snapshot, a shipping address, a discount code, a shipping fee, and operator/customer notes, and can freely edit or discard it until it is finalized.
Save a custom line with Add item below the input fields. Drafts without saved calculation results show Not calculated in the summary; select Recalculate to check the amounts. Unavailable product information uses a descriptive title and an available SKU instead of internal IDs. Custom lines without a title use a default title in the Admin language.
If the line creation outcome could not be verified, the draft order lines refresh. Check for an already saved line before adding it again.
Operators can save the draft email directly in the composer's customer email field. The email-only update preserves the latest server-side customer name and phone, and the Complete order button stays disabled while the email is blank or invalid, has unsaved changes, or is being saved. Completion is enabled again only after the save response reads the email back. A failed save keeps the input and focus available for retry; an email-specific completion rejection stays with the email field without invalidating the displayed totals. Completion preview and confirmation lock both the email input and save action, while completed, finalized, and discarded drafts show the email in the customer summary in place of an edit field.
A draft reserves no inventory and creates no order ledger rows (orders, transactions, inventory reservations, fulfillment) before finalization. POST /api/draft-orders/:id/calculate returns a server-derived totals preview (subtotal, discount, shipping, total) with no side effects and surfaces unavailable or out-of-stock variants and an invalid discount code before finalize.
POST /api/draft-orders/:id/finalize converts the draft into a real order. Pricing, discounts, workspace checks, idempotency, and lifecycle defaults reuse the same server-derived order-creation path as storefront orders, and the resulting order records source = manual. A zero-amount draft follows the existing free-order auto-paid path; otherwise a manual pending order is created for follow-up. If the customer email is missing or invalid, finalize is rejected with a clear error and the draft stays editable.
The v1 scope covers catalog items, directly entered items, and an existing discount code. Catalog items use server prices, and directly entered items are calculated using the unit price entered by the operator. Currency is fixed to KRW, and finalize does not send payment or invoice links (a later phase). Draft status moves draft → finalized (linked to the created order) or discarded; a finalized or discarded draft can no longer be edited.
Launch Checklist
- ecommerce is effective on the current plan
- at least one product is ready for sale
- shipping and discount ownership are clear
- customer support owns account and order questions
- payment and webhook responsibilities are assigned before customer launch
Keep commerce launch small. A complete first product and order support path is better than a broad catalog with unclear ownership.
Commerce helpers (SDK)
This section hands implementation to the technical owner. Daily catalog, order, fulfillment, return, and draft-order procedures remain above. The Ecommerce guide completes one guest nonshipping purchase through Cart, Checkout, configured PortOne Standard V2 and same-order readback; completing it does not complete the operating or launch checklists.
Start with that complete public purchase workflow and connect its typed durable port to your existing app session/store. Confirm the installed SDK version before copying calls. The references below cover catalog details and specialist operations.
Product media is ordered. The first product image is the representative image for listing cards and the initial product detail view.
| Technical handoff | Reference |
|---|---|
| Public-safe catalog detail, cards, markets and stock checks | Ecommerce SDK |
| PortOne action reuse, server-only recovery, and independently verified custom payments | Payments |
| Membership plans, renewals, benefit access, and unapplied paid evidence | Membership |
| Workspace-operated providers and fulfillment workers | External Effects |
| Eligible external PG refund workers | Webhooks: orderCanceled refund handoff |
The technical owner must keep server credentials and provider verification on trusted servers. Public catalog responses exclude raw stock quantities; server product detail has a different trust boundary. Browser redirects or SDK payment results trigger authoritative verification and never prove payment finality. Unknown payment/refund outcomes need reconciliation before another attempt. Review the specialist references before handing off implementation.
Next Actions
- Review credentials and webhooks in Integrations & Keys.
- Run commerce blockers through Launch Readiness.
- Return to Feature Planning before adding customer accounts or community workflows.