Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Use Founder / Developer tabs in the docs sidebar to filter this page. Legacy copy invented vendor apply endpoints, PUT product/order status routes, and Solidity RING payment contracts — those are not under app/api/store/. Cart truth: guests use localStorage ring_cart; authenticated buyers also mirror via GET/POST /api/store/cart (+ optional soft-hold).
Ring’s multi-vendor store exposes: catalog + reviews + product agent chat, guest cart + session cart mirror, orders / checkout, and payments via PaymentConductor purpose store_order (ledger SSOT in payment_transactions).
| Concern | Where it lives |
|---|---|
| Guest cart | Client ring_cart (features/store/context.tsx) |
| Auth cart mirror | GET/POST /api/store/cart — binds session.user.id only; ignores body userId |
| Soft-hold | POST /api/store/cart/hold — inventory soft-hold while cart has lines (may 409) |
| Catalog / create product | GET/POST /api/store/products |
| Place order | POST /api/store/orders or POST /api/store/checkout (same orders pipeline) |
| Pay | POST /api/store/payments/wayforpay or …/credit → PaymentConductor |
| Vendor onboarding | /vendor/start + server actions — not REST under /api/store/vendors |
Buyers browse the catalog, build a cart in the browser, confirm address, create an order, then pay by card (WayForPay) or internal credit when you enable it. Vendors list products after approval; commissions and settlements run after payment — not at “add to cart.”
Use Founder / Developer tabs in the docs sidebar to filter this page. Legacy copy invented vendor apply endpoints, PUT product/order status routes, and Solidity RING payment contracts — those are not under app/api/store/. Cart truth: guests use localStorage ring_cart; authenticated buyers also mirror via GET/POST /api/store/cart (+ optional soft-hold).
Ring’s multi-vendor store exposes: catalog + reviews + product agent chat, guest cart + session cart mirror, orders / checkout, and payments via PaymentConductor purpose store_order (ledger SSOT in payment_transactions).
| Concern | Where it lives |
|---|---|
| Guest cart | Client ring_cart (features/store/context.tsx) |
| Auth cart mirror | GET/POST /api/store/cart — binds session.user.id only; ignores body userId |
| Soft-hold | POST /api/store/cart/hold — inventory soft-hold while cart has lines (may 409) |
| Catalog / create product | GET/POST /api/store/products |
| Place order | POST /api/store/orders or POST /api/store/checkout (same orders pipeline) |
| Pay | POST /api/store/payments/wayforpay or …/credit → PaymentConductor |
| Vendor onboarding | /vendor/start + server actions — not REST under /api/store/vendors |
Buyers browse the catalog, build a cart in the browser, confirm address, create an order, then pay by card (WayForPay) or internal credit when you enable it. Vendors list products after approval; commissions and settlements run after payment — not at “add to cart.”
Use Founder / Developer tabs in the docs sidebar to filter this page. Legacy copy invented vendor apply endpoints, PUT product/order status routes, and Solidity RING payment contracts — those are not under app/api/store/. Cart truth: guests use localStorage ring_cart; authenticated buyers also mirror via GET/POST /api/store/cart (+ optional soft-hold).
Ring’s multi-vendor store exposes: catalog + reviews + product agent chat, guest cart + session cart mirror, orders / checkout, and payments via PaymentConductor purpose store_order (ledger SSOT in payment_transactions).
| Concern | Where it lives |
|---|---|
| Guest cart | Client ring_cart (features/store/context.tsx) |
| Auth cart mirror | GET/POST /api/store/cart — binds session.user.id only; ignores body userId |
| Soft-hold | POST /api/store/cart/hold — inventory soft-hold while cart has lines (may 409) |
| Catalog / create product | GET/POST /api/store/products |
| Place order | POST /api/store/orders or POST /api/store/checkout (same orders pipeline) |
| Pay | POST /api/store/payments/wayforpay or …/credit → PaymentConductor |
| Vendor onboarding | /vendor/start + server actions — not REST under /api/store/vendors |
Buyers browse the catalog, build a cart in the browser, confirm address, create an order, then pay by card (WayForPay) or internal credit when you enable it. Vendors list products after approval; commissions and settlements run after payment — not at “add to cart.”
Internal credit balance used by store credit checkout.
GET /api/store/products (filters: search, categories, price, stock, sort).ring_cart in the browser. Signed-in: hydrate/sync via GET/POST /api/store/cart (server wins on hydrate).POST /api/store/orders (or /checkout); stock hold may return 409 if inventory fails./vendor/start, not /api/store/vendors/apply.VendorSettlementService); configure trust tiers and store payment env, not fake on-chain RING contracts on this page.PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES=UAH (or your accepted list); otherwise buyers use card.Prefer the store UI and vendor/admin actions for day-to-day ops. Call these routes when automating checkout or integrating a custom storefront against the same order + PaymentConductor pipeline.
| POST | /api/store/cart/hold | Session | Soft-hold inventory for current cart lines |
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /api/store/products | Public | Filters: search, categories, priceMin, priceMax, inStock, sortBy, currency, limit, afterId |
| POST | /api/store/products | Session; vendor approved or platform admin | Creates product; updateTag('store:products') |
| GET, POST | /api/store/products/[id]/reviews | GET public; POST session | Zod rating/content; verified-purchase when order history matches |
| GET, POST | /api/store/products/[id]/agent-chat | Session | Product agent conversation; POST may SSE-stream |
| GET | /api/store/price-range | Public | Min/max for catalog filters (excludes price slider) |
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /api/store/orders | Session | User’s orders; limit, afterId |
| POST | /api/store/orders | Session | Zod orderCreateSchema; referral cookie; reserveInventoryForOrder → 409 + cancel on stock fail |
| GET | /api/store/orders/[id] | Session (owner) | Order by id |
| POST | /api/store/checkout | Session | Canonical checkout → same StoreOrdersService / orders pipeline as POST orders (not legacy store_orders) |
| Method | Path | Auth | Notes |
|---|---|---|---|
| POST | /api/store/payments/wayforpay | Session (order owner) | PaymentConductor.createCheckout({ purpose: 'store_order', rail: 'merchant_redirect' }) |
| POST | /api/store/payments/credit | Session (order owner) | Rail credit_balance; may reject UAH unless PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES allows it |
| GET | /api/store/payments/[orderId]/status | Session (owner or admin) | Poll status / WayForPay when initiated |
| POST | /api/store/payments/wayforpay/webhook | Gateway | Deprecated alias — prefer /api/payments/wayforpay/webhook |
Not live as store REST: /api/store/vendors, /api/store/vendors/apply, PUT product or order-status under /api/store/*. Vendor MCP lives under app/api/mcp/v1/store/vendors/*. Order status advances via admin/store services and actions.
/api/store/cart, /hold), product create, orders list/create, checkout, payments, agent-chat, review create, payment status.auth() in route handlers). Guests keep ring_cart until sign-in hydrates the server mirror.Create the order (POST /api/store/orders or /checkout) and keep orderId.
Call WayForPay initiation — body { orderId, returnUrl?, locale? } (UK | EN | RU).
Redirect the buyer to paymentUrl. Canonical webhook: POST /api/payments/wayforpay/webhook (store alias only for legacy merchants).
| Variable | Role |
|---|---|
PAYMENT_STORE_PROCESSOR | Optional override for store_order processor (else default) |
PAYMENT_STORE_ALLOW_CREDIT | Credit rail for store (default allow unless false) |
PAYMENT_STORE_ALLOW_TOKEN | Opt-in token rail (=== 'true' in payment.config) |
PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES | e.g. UAH to allow credit on UAH carts |
WAYFORPAY_MERCHANT_ACCOUNT / WAYFORPAY_SECRET_KEY / WAYFORPAY_DOMAIN | WayForPay SSOT (no MERCHANT_ID) |
WAYFORPAY_STORE_* | Optional store-specific overrides of the above |
| Path | Role |
|---|---|
lib/payments/conductor/payment-conductor.ts | createCheckout entry |
lib/payments/processors/wayforpay.processor.ts | store_order merchant redirect |
lib/payments/conductor/handlers/store-order.ts | Webhook / paid handler |
features/store/services/orders-service.ts | Order CRUD / payment status |
features/store/services/inventory-sync.ts | reserveInventoryForOrder |
features/store/services/vendor-settlement.ts | Post-pay settlements |
features/store/context.tsx | Guest cart ring_cart + hydrate against /api/store/cart when signed in |
features/store/services/server-cart.ts | Session cart mirror used by /api/store/cart |
app/api/store/cart/route.ts, …/hold/route.ts | Auth cart GET/POST + soft-hold |
app/_actions/vendor-actions.ts, store-products.ts, store-address-actions.ts, store-erp.ts | Vendor/admin/address/ERP actions |
Referral cookie on POST orders.
Internal credit balance used by store credit checkout.
GET /api/store/products (filters: search, categories, price, stock, sort).ring_cart in the browser. Signed-in: hydrate/sync via GET/POST /api/store/cart (server wins on hydrate).POST /api/store/orders (or /checkout); stock hold may return 409 if inventory fails./vendor/start, not /api/store/vendors/apply.VendorSettlementService); configure trust tiers and store payment env, not fake on-chain RING contracts on this page.PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES=UAH (or your accepted list); otherwise buyers use card.Prefer the store UI and vendor/admin actions for day-to-day ops. Call these routes when automating checkout or integrating a custom storefront against the same order + PaymentConductor pipeline.
| POST | /api/store/cart/hold | Session | Soft-hold inventory for current cart lines |
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /api/store/products | Public | Filters: search, categories, priceMin, priceMax, inStock, sortBy, currency, limit, afterId |
| POST | /api/store/products | Session; vendor approved or platform admin | Creates product; updateTag('store:products') |
| GET, POST | /api/store/products/[id]/reviews | GET public; POST session | Zod rating/content; verified-purchase when order history matches |
| GET, POST | /api/store/products/[id]/agent-chat | Session | Product agent conversation; POST may SSE-stream |
| GET | /api/store/price-range | Public | Min/max for catalog filters (excludes price slider) |
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /api/store/orders | Session | User’s orders; limit, afterId |
| POST | /api/store/orders | Session | Zod orderCreateSchema; referral cookie; reserveInventoryForOrder → 409 + cancel on stock fail |
| GET | /api/store/orders/[id] | Session (owner) | Order by id |
| POST | /api/store/checkout | Session | Canonical checkout → same StoreOrdersService / orders pipeline as POST orders (not legacy store_orders) |
| Method | Path | Auth | Notes |
|---|---|---|---|
| POST | /api/store/payments/wayforpay | Session (order owner) | PaymentConductor.createCheckout({ purpose: 'store_order', rail: 'merchant_redirect' }) |
| POST | /api/store/payments/credit | Session (order owner) | Rail credit_balance; may reject UAH unless PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES allows it |
| GET | /api/store/payments/[orderId]/status | Session (owner or admin) | Poll status / WayForPay when initiated |
| POST | /api/store/payments/wayforpay/webhook | Gateway | Deprecated alias — prefer /api/payments/wayforpay/webhook |
Not live as store REST: /api/store/vendors, /api/store/vendors/apply, PUT product or order-status under /api/store/*. Vendor MCP lives under app/api/mcp/v1/store/vendors/*. Order status advances via admin/store services and actions.
/api/store/cart, /hold), product create, orders list/create, checkout, payments, agent-chat, review create, payment status.auth() in route handlers). Guests keep ring_cart until sign-in hydrates the server mirror.Create the order (POST /api/store/orders or /checkout) and keep orderId.
Call WayForPay initiation — body { orderId, returnUrl?, locale? } (UK | EN | RU).
Redirect the buyer to paymentUrl. Canonical webhook: POST /api/payments/wayforpay/webhook (store alias only for legacy merchants).
| Variable | Role |
|---|---|
PAYMENT_STORE_PROCESSOR | Optional override for store_order processor (else default) |
PAYMENT_STORE_ALLOW_CREDIT | Credit rail for store (default allow unless false) |
PAYMENT_STORE_ALLOW_TOKEN | Opt-in token rail (=== 'true' in payment.config) |
PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES | e.g. UAH to allow credit on UAH carts |
WAYFORPAY_MERCHANT_ACCOUNT / WAYFORPAY_SECRET_KEY / WAYFORPAY_DOMAIN | WayForPay SSOT (no MERCHANT_ID) |
WAYFORPAY_STORE_* | Optional store-specific overrides of the above |
| Path | Role |
|---|---|
lib/payments/conductor/payment-conductor.ts | createCheckout entry |
lib/payments/processors/wayforpay.processor.ts | store_order merchant redirect |
lib/payments/conductor/handlers/store-order.ts | Webhook / paid handler |
features/store/services/orders-service.ts | Order CRUD / payment status |
features/store/services/inventory-sync.ts | reserveInventoryForOrder |
features/store/services/vendor-settlement.ts | Post-pay settlements |
features/store/context.tsx | Guest cart ring_cart + hydrate against /api/store/cart when signed in |
features/store/services/server-cart.ts | Session cart mirror used by /api/store/cart |
app/api/store/cart/route.ts, …/hold/route.ts | Auth cart GET/POST + soft-hold |
app/_actions/vendor-actions.ts, store-products.ts, store-address-actions.ts, store-erp.ts | Vendor/admin/address/ERP actions |
Referral cookie on POST orders.
Internal credit balance used by store credit checkout.
GET /api/store/products (filters: search, categories, price, stock, sort).ring_cart in the browser. Signed-in: hydrate/sync via GET/POST /api/store/cart (server wins on hydrate).POST /api/store/orders (or /checkout); stock hold may return 409 if inventory fails./vendor/start, not /api/store/vendors/apply.VendorSettlementService); configure trust tiers and store payment env, not fake on-chain RING contracts on this page.PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES=UAH (or your accepted list); otherwise buyers use card.Prefer the store UI and vendor/admin actions for day-to-day ops. Call these routes when automating checkout or integrating a custom storefront against the same order + PaymentConductor pipeline.
| POST | /api/store/cart/hold | Session | Soft-hold inventory for current cart lines |
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /api/store/products | Public | Filters: search, categories, priceMin, priceMax, inStock, sortBy, currency, limit, afterId |
| POST | /api/store/products | Session; vendor approved or platform admin | Creates product; updateTag('store:products') |
| GET, POST | /api/store/products/[id]/reviews | GET public; POST session | Zod rating/content; verified-purchase when order history matches |
| GET, POST | /api/store/products/[id]/agent-chat | Session | Product agent conversation; POST may SSE-stream |
| GET | /api/store/price-range | Public | Min/max for catalog filters (excludes price slider) |
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /api/store/orders | Session | User’s orders; limit, afterId |
| POST | /api/store/orders | Session | Zod orderCreateSchema; referral cookie; reserveInventoryForOrder → 409 + cancel on stock fail |
| GET | /api/store/orders/[id] | Session (owner) | Order by id |
| POST | /api/store/checkout | Session | Canonical checkout → same StoreOrdersService / orders pipeline as POST orders (not legacy store_orders) |
| Method | Path | Auth | Notes |
|---|---|---|---|
| POST | /api/store/payments/wayforpay | Session (order owner) | PaymentConductor.createCheckout({ purpose: 'store_order', rail: 'merchant_redirect' }) |
| POST | /api/store/payments/credit | Session (order owner) | Rail credit_balance; may reject UAH unless PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES allows it |
| GET | /api/store/payments/[orderId]/status | Session (owner or admin) | Poll status / WayForPay when initiated |
| POST | /api/store/payments/wayforpay/webhook | Gateway | Deprecated alias — prefer /api/payments/wayforpay/webhook |
Not live as store REST: /api/store/vendors, /api/store/vendors/apply, PUT product or order-status under /api/store/*. Vendor MCP lives under app/api/mcp/v1/store/vendors/*. Order status advances via admin/store services and actions.
/api/store/cart, /hold), product create, orders list/create, checkout, payments, agent-chat, review create, payment status.auth() in route handlers). Guests keep ring_cart until sign-in hydrates the server mirror.Create the order (POST /api/store/orders or /checkout) and keep orderId.
Call WayForPay initiation — body { orderId, returnUrl?, locale? } (UK | EN | RU).
Redirect the buyer to paymentUrl. Canonical webhook: POST /api/payments/wayforpay/webhook (store alias only for legacy merchants).
| Variable | Role |
|---|---|
PAYMENT_STORE_PROCESSOR | Optional override for store_order processor (else default) |
PAYMENT_STORE_ALLOW_CREDIT | Credit rail for store (default allow unless false) |
PAYMENT_STORE_ALLOW_TOKEN | Opt-in token rail (=== 'true' in payment.config) |
PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES | e.g. UAH to allow credit on UAH carts |
WAYFORPAY_MERCHANT_ACCOUNT / WAYFORPAY_SECRET_KEY / WAYFORPAY_DOMAIN | WayForPay SSOT (no MERCHANT_ID) |
WAYFORPAY_STORE_* | Optional store-specific overrides of the above |
| Path | Role |
|---|---|
lib/payments/conductor/payment-conductor.ts | createCheckout entry |
lib/payments/processors/wayforpay.processor.ts | store_order merchant redirect |
lib/payments/conductor/handlers/store-order.ts | Webhook / paid handler |
features/store/services/orders-service.ts | Order CRUD / payment status |
features/store/services/inventory-sync.ts | reserveInventoryForOrder |
features/store/services/vendor-settlement.ts | Post-pay settlements |
features/store/context.tsx | Guest cart ring_cart + hydrate against /api/store/cart when signed in |
features/store/services/server-cart.ts | Session cart mirror used by /api/store/cart |
app/api/store/cart/route.ts, …/hold/route.ts | Auth cart GET/POST + soft-hold |
app/_actions/vendor-actions.ts, store-products.ts, store-address-actions.ts, store-erp.ts | Vendor/admin/address/ERP actions |
Referral cookie on POST orders.