Commerce Operations

Use this page when the workspace will sell products, manage customers, or support orders after launch.

Commerce Setup

Operating Ownership

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.

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.

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.

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 a legacy discounted snapshot's default 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.

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

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) - returnShippingFee

The 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.

Manual Orders (Draft Orders)

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.

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 expose a focusable read-only email that can still be selected and copied.

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 server-priced catalog items plus an existing discount code. There is no manual or custom line pricing, 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.

Personal order views

In the Admin Panel Orders list, My order views saves the current filters and column order/visibility under a name. Views are private to your account in the selected workspace. Choose a saved view and click Apply; views never apply automatically after reconnecting or switching workspaces.

The list shows up to 1,000 personal views per workspace, sorted by name and then ID. There is no creation count limit; if you save more, views beyond the first 1,000 are omitted from the list.

Names have 1–80 characters, ignore surrounding whitespace, and distinguish uppercase from lowercase. Duplicate names are rejected. tenant-admin and tenant-editor can save, rename, and delete their own views. tenant-viewer can apply existing personal views while Orders access remains available.

Applying resets the page to 1 and keeps the current sort, search, and page size. Columns continue to use the existing account-level list preferences. Changing filters or columns after applying does not edit the saved view; save a new view explicitly. Deleting a view leaves the current list unchanged. If a view can no longer be applied, delete it and save the current settings again. Views are unavailable after workspace access or ecommerce is revoked.

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

Commerce helpers (SDK)

This section hands implementation to the technical owner. Daily catalog, order, fulfillment, return, and draft-order procedures remain above. The Ecommerce P0 task guide implements a representative app purchase flow; completing it does not complete the operating or launch checklists.

The SDK README retains the detailed Cart, Checkout, PaymentSession, product, discount/shipping and React helper usage. Confirm the installed package version before copying implementation calls. The references below add task-specific context.

Product media is ordered. The first product image is the representative image for listing cards and the initial product detail view.

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.