Svelte Commerce × OroCommerce
Svelte Commerce on OroCommerce
OroCommerce’s storefront API speaks JSON:API, and the connector ships a deserialiser that resolves included relationships. Cart, checkout and sign-in are wired; reviews, wishlist, currencies and vendors are the gaps.
- 21/43 services wired
- @misiki/orocommerce-connector 0.4.0
- Cart wired
- Checkout wired
- Sign-in (auth) wired
What works on OroCommerce today
Cart, checkout and sign-in are wired; reviews, wishlist, currencies and vendors are not. There is no cash on delivery — OroCommerce has no such payment method — so orders go through Oro’s PayPal Express or Stripe checkout.
Cart
Wired: issues a real request to OroCommerce.
Checkout
Wired: issues a real request to OroCommerce.
Sign-in (auth)
Wired: issues a real request to OroCommerce.
Known gaps: review, wishlist, currency, vendor
21 of 43 services wired, read from CONNECTORS.md on ; npm may carry a newer patch. How coverage is measured.
What the connector calls on OroCommerce
The connector calls OroCommerce’s storefront JSON:API under {apiUrl}/api, sending application/vnd.api+json as both Accept and Content-Type, and stays off the back-office API at /admin/api, whose tokens it treats as not interchangeable.
Every request carries Authorization: Bearer <access_token> from an OAuth2 password grant on {apiUrl}/oauth2-token (outside /api, plain JSON, with client_id and client_secret from the API key and secret); an anonymous shopper gets a visitor token from the same grant with the literal username and password guest, a signed-in customer user gets one with their email and password, and both tokens are kept in the oro_access_token and oro_refresh_token cookies and refreshed once on a 401.
| Service | What it requests |
|---|---|
product | GET /api/products with include=images, filter[variants]=0 and a sort; GET /api/products/{id} with include=images,variantProducts |
search | GET /api/productsearch with filter[searchQuery]=allText ~ "…", filter[aggregations] for facets and a sort |
category | GET /api/mastercatalogtree?include=category for the whole tree; GET /api/products?filter[rootCategory]={id} for a category’s products |
cart | GET /api/shoppinglists/default?include=items,items.product,items.unit; POST, PATCH and DELETE /api/shoppinglistitems for lines |
checkout | POST /api/shoppinglists/{id}/checkout to start; GET /api/checkouts/{id}/availableShippingMethods and availablePaymentMethods; PATCH /api/checkouts/{id} to set the methods |
payment | GET /api/checkouts/{id}/payment, then POST to the meta.paymentUrl it returns; POST /api/checkouts/{id}/paymentPayPalExpress or paymentStripePaymentElement when that gateway is asked for |
order | GET /api/orders with include=lineItems,status and filter[identifier] for an order number; GET /api/orders/{id} |
auth | GET /api/customerusers/mine after sign-in; POST /api/customerusers to register |
OroCommerce rules the connector follows
- Oro’s storefront API has no
meta.totalCountand noLinkheader, so every paged read sendsX-Include: totalCountand reads the total from theX-Include-Total-Countresponse header. - The cart is a shopping list, addressed by the literal id
default, which Oro resolves on the server to the current visitor’s or customer user’s list; the connector caches no cart id, so a sign-in or sign-out never points at the previous session’s list. - At sign-in the connector forwards the stored visitor token as
visitor_access_token, which is what moves the guest’s shopping list onto the customer user. - A product or category slug is resolved through
GET /api/routes/{id}, whose id is the storefront path with every slash replaced by a colon, so/products/medicalbecomes:products:medical. - Product sorting is limited to
createdAt,updatedAt,idandsku, because Oro answers any other sorter with a 400; an unknown sort falls back to-id.
Read from the source of misiki-in/orocommerce-connector at commit 54ab290 of . Where the code has changed since, the code is right.
Quick start
From nothing to a Svelte Commerce storefront reading OroCommerce. You need Node.js and a OroCommerce to point it at; the storefront holds no data of its own.
Clone it, choose the connector, point it at OroCommerce
# 1 — get the storefront
git clone https://github.com/itswadesh/svelte-commerce
cd svelte-commerce
# 2 — one connector at a time: remove the two the storefront ships with, add this one
npm uninstall @misiki/litekart-connector @misiki/vendure-connector
npm i @misiki/orocommerce-connector
# 3 — point it at your OroCommerce website
echo PUBLIC_OROCOMMERCE_API_URL=https://your-store.example.com >> .env
echo PUBLIC_OROCOMMERCE_API_KEY=... >> .env
echo PUBLIC_OROCOMMERCE_API_SECRET=... >> .env
# 4 — run it
npm run devSwitching works the same way on every backend: what all 26 share, from one connector at a time to store identity.
Environment variables
| Variable | Required | What it does |
|---|---|---|
PUBLIC_OROCOMMERCE_API_URL | Yes | The website origin: the storefront JSON:API lives at {url}/api and the token endpoint at {url}/oauth2-token. Boot fails, naming this variable, if it is missing. |
PUBLIC_OROCOMMERCE_API_KEY | No | OAuth2 client_id. |
PUBLIC_OROCOMMERCE_API_SECRET | No | OAuth2 client_secret. See the limitations. |
PUBLIC_OROCOMMERCE_ACCESS_TOKEN | No | Sent as a bearer token when set. |
PUBLIC_OROCOMMERCE_LOCALIZATION_ID | No | Sent as X-Localization-ID: the locale every localised field comes back in. |
PUBLIC_OROCOMMERCE_CURRENCY | No | Sent as X-Currency. OroCommerce Enterprise only; Community Edition ignores it. |
PUBLIC_OROCOMMERCE_PRODUCT_ID_MODE | No | sku addresses products by SKU instead of numeric ID, sent as X-Product-ID: sku on every request. |
PUBLIC_CONNECTOR | No | Only when more than one connector is installed: @misiki/orocommerce-connector names the one this build runs on. |
init.ts hands the connector every PUBLIC_OROCOMMERCE_* variable that is set, camel-cased. The guide also lists PUBLIC_OROCOMMERCE_STORE_ID and PUBLIC_OROCOMMERCE_CHANNEL_ID, which Oro ignores — it resolves the website from the request’s host — and PUBLIC_OROCOMMERCE_ACCESS_KEY, which the connector’s source does not read.
Every variable here begins PUBLIC_, and SvelteKit sends PUBLIC_ variables to the browser: treat each value you set as published.
What to set up on OroCommerce
- Create an OAuth application for the storefront API; its client ID and secret go in
PUBLIC_OROCOMMERCE_API_KEYandPUBLIC_OROCOMMERCE_API_SECRET— read the limitations first. - Configure PayPal Express or Stripe on the Oro side if shoppers are to pay: OroCommerce has no cash-on-delivery method, and the storefront’s cash-on-delivery option throws.
How the integration works
Oro’s storefront API answers in JSON:API, and the connector resolves included relationships with its own deserialiser (the jsonapi file in its source is that helper, not a service). The website is resolved from the request’s host; locale, currency and SKU addressing travel as Oro’s documented headers. Payment goes through Oro’s checkout endpoints for PayPal Express and Stripe.
Limitations on OroCommerce
- No cash on delivery: OroCommerce has no such payment method, so the storefront’s cash-on-delivery option throws
NotSupportedError. - The OAuth client ID and secret come from
PUBLIC_OROCOMMERCE_API_KEYandPUBLIC_OROCOMMERCE_API_SECRET. SvelteKit sendsPUBLIC_variables to the browser, so every visitor can read them.
Before you rely on it
No connector has been exercised against a live production instance of its platform; each was written from the platform’s published source. The limits every backend shares and the errors every switch can meet are on the backends page.
Offer a sandbox or a correctionFAQ
Questions about Svelte Commerce on OroCommerce
Can I run an OroCommerce store on Svelte Commerce today?
Cart, checkout and sign-in are wired; reviews, wishlist, currencies and vendors are not, and there is no cash on delivery. Like every connector, it has not been run against a live production OroCommerce store.
How do I switch Svelte Commerce to OroCommerce?
Remove the connectors the storefront ships with, install @misiki/orocommerce-connector, set PUBLIC_OROCOMMERCE_API_URL in .env and start the dev server. vite.config.ts resolves whichever connector is installed, so no file in the storefront changes.
How do shoppers pay on OroCommerce?
Through Oro’s own checkout endpoints for PayPal Express and Stripe. OroCommerce has no cash-on-delivery payment method, so that option in the storefront throws rather than pretend.
Sources
OROCOMMERCE.md, read on ; CONNECTORS.md, read on ; the connector’s source at 54ab290. Where they disagree with this page, they are right. OroCommerce is a trademark of its owner, named only to describe compatibility; see trademarks.