Skip to main content

​
Unified Commercial Suite architecture

​
Runtime

The embedded admin app runs on Cloudflare Workers with React Router 7 and Vite. Shopify sessions and B2B business data are stored in Cloudflare D1. A Cloudflare Queue and a Durable Object coordinate asynchronous customer-tag synchronization, and the queue also carries delayed privacy-export retries. Shopify Admin GraphQL is the source of truth for catalog, customer, order, draft-order, and billing records.

​
Interfaces and data flow

  • Admin routes (/app/*) authenticate a verified Shopify admin session. Reads use the session; company and price-list mutations additionally require the account owner.
  • Admin APIs (/api/*) authenticate the same Shopify session and return a consistent JSON envelope ({ "success": true, "data": ... } or { "success": false, "error": ... }).
  • App proxy (/apps/b2b-toolkit) is the signed storefront surface: pricing and quote requests, and the wholesale registration form. Shopify signs each forwarded request, so no tenant or customer identity is accepted from JavaScript.
  • Merchant API (/api/merchant/*) is a separate Premium REST surface authenticated with a bearer key.
  • Webhooks (/webhooks) accept POST only and verify Shopify’s HMAC-SHA256 signature.
The storefront theme embed calls the signed pricing proxy and applies B2B unit prices for signed-in buyers. Draft-order checkout fetches authoritative variant, product, and collection data from Shopify Admin GraphQL and applies B2B pricing and order limits on the server.

​
Checkout enforcement

Two Shopify Functions enforce B2B rules on standard checkouts alongside the manual draft-order path:
  • b2b-checkout-pricing targets cart.lines.discounts.generate.run.
  • b2b-order-limits targets cart.validations.generate.run.
The functions read app-owned JSON metafields in the $app:pcnaid_b2b namespace, hydrated from the backend, so policy is not merchant-editable through custom data. They validate time windows and company status so scheduled price lists and inactive companies behave correctly.

​
Server libraries

See the API overview for documented interfaces and the quickstart to get oriented. For plain-English merchant instructions, see the merchant guides. Pcnaid Documentation › Shopify Ecosystem › Unified Commercial Suite › Developer