Skip to main content

​
Unified Commercial Suite API overview

​
Surfaces and authentication

Admin APIs return a consistent envelope:
Errors return:

​
Error codes

​
Companies API

Base: /api/companies. Reads use a verified Shopify admin session; mutations require account-owner authorization.
  • GET /api/companies — list companies.
  • POST /api/companies (application/x-www-form-urlencoded) with action of create, update, or delete.
Create and update fields include name, paymentTerms (net15, net30, net45, net60, net90), discountPercentage, externalId, b2bTier, taxExempt, assignedRep, minimumOrderQuantity, and maximumOrderValue. A Shopify Company GID as externalId requires Shopify Plus and the Premium company_accounts entitlement. These endpoints are called by the embedded admin and require a Shopify admin session; they cannot be called with curl directly. The storefront wholesale application form is served through the app proxy at /apps/b2b-toolkit/register on the store domain.

​
Price lists API

Base: /api/pricelists. Mutations enforce plan limits and can return 402.
  • GET /api/pricelists — list price lists.
  • GET /api/pricelists?id=1 — get one price list with its rules.
  • POST /api/pricelists with action of create, update, delete, add_rule, delete_rule, assign_to_company, or unassign_from_company.
Rule fields include ruleType (percentage_discount, fixed_price, or collection_discount), variantId, productId, collectionId, discountPercentage, fixedPrice, currency, and minQuantity.

​
Checkout API

Base: /api/checkout. POST only. Authenticates a Shopify staff session plus plan, tenant, buyer, pricing, and order-limit checks. Like the other Admin APIs, checkout is called by the embedded admin and requires a verified Shopify admin session; it cannot be called with curl directly. The endpoint ignores client-derived catalog details and fetches the current variant price, product, collections, and shop currency from Shopify Admin GraphQL before calculating B2B price and order limits. Corporate buyers can receive 202 with approvalRequired: true. For a taxable company whose customer remains independently exempt, it returns 409 with code: "CUSTOMER_TAX_EXEMPT_CONFLICT"; a stale relationship to a deleted customer returns 404 with code: "SHOPIFY_CUSTOMER_NOT_FOUND".

​
App proxy - pricing

Public path: /apps/b2b-toolkit/pricing on the store domain. HMAC-validated; publicly reachable from the storefront. Shopify proxies this to the app’s internal /proxy/pricing route.
  • GET /apps/b2b-toolkit/pricing?variants=... returns isB2B and the customer’s rules.
  • POST /apps/b2b-toolkit/pricing with an items array returns calculated prices.

​
App proxy - quotes

Public path: /apps/b2b-toolkit/quotes on the store domain. HMAC-validated. The theme RFQ block requires product context. Shopify proxies this to the app’s internal /proxy/quotes route.
  • POST /apps/b2b-toolkit/quotes submits a quote request and returns 201 with a quoteNumber.
  • GET /apps/b2b-toolkit/quotes lists the customer’s quotes.

​
Import / export API

Base: /api/import-export. Reads use a verified Shopify admin session; mutations require account-owner authorization.
  • GET /api/import-export?entity=companies&format=csv returns raw CSV with Content-Disposition: attachment.
  • POST /api/import-export with intent of import_companies or import_contacts and a csv field. Contact rows require company_external_id and shopify_customer_id; role defaults to member and accepts admin, member, or viewer.

​
Merchant API

Base: /api/merchant/*. Premium plan. Keys are managed in the embedded admin at /app/merchant-api. Supported scopes are read:companies, read:price_lists, read:quotes, and write:quotes.
  • GET /api/merchant/companies
  • GET /api/merchant/price-lists
  • GET /api/merchant/quotes
  • GET /api/merchant/quotes/:id
  • POST /api/merchant/quotes/:id with { "action": "accept" }

​
Webhooks

Base: /webhooks. POST only. The endpoint verifies Shopify’s HMAC-SHA256 signature. Outbound webhooks (Premium) are delivered with HMAC-SHA256; verify the x-ucs-signature header with your signing secret. Endpoints are managed at /app/merchant-api.

​
Rate limits

The application does not implement a custom request-rate limiter. Cloudflare Worker and D1 quotas are account-plan and platform limits. Shopify Admin GraphQL calls remain subject to Shopify’s query-cost throttling. Pcnaid Documentation › Shopify Ecosystem › Unified Commercial Suite › Developer