Does Medusa Work in China? PIPL Cross-Border, ICP Filing & Data Residency

Medusa is an MIT-licensed, self-hostable commerce platform, so whether it works in mainland China is decided by where you run it: a store hosted offshore keeps your customers' PII and orders outside the mainland — a PIPL cross-border transfer — the storefront still needs an ICP filing, and China payment runs through a licensed domestic path. A compliance-first look at the residency, ICP and payment exposure.

By the 21YunBox Compliance Team · Reviewed 2026-10-10 · Verified against Medusa's own documentation

Does Medusa work in China?

Medusa has no China region to switch on — its MIT-licensed core is software you self-host, so whether it "works" in mainland China is decided by where you run the server and what you do with the customer PII and orders it stores, not by Medusa.

Medusa is a platform to "build custom commerce applications," and its deployment docs say "your server connects to a PostgreSQL database" on a Node.js host you choose — so the customer names, addresses, phone numbers, orders and behavior it keeps live wherever you deploy. Host that store offshore to serve mainland shoppers and you are making a PIPL cross-border transfer of their personal information; the public storefront still needs an ICP filing, and China payment runs through a licensed domestic path. Because the core is open-source and self-hostable, the lawful lever is to keep store data in-country — self-host the engine on the mainland — ICP-file the delivery path, and route payment through a licensed domestic provider, not to make an offshore storefront reachable (21YunBox is advisory on payment).

This is a risk map, not a verdict — which filing, cross-border mechanism and payment path you need turn on your entity, your hosting and who your shoppers are. Our China team can map your exposure →

What Medusa's own documentation says about China

Fact	Primary source
Medusa's core is MIT-licensed, self-hosted software — there is no Medusa-operated China region to switch on. Medusa's own README states, "Medusa uses an open-core model. The core is licensed under the MIT License," and that it is a platform to "build custom commerce applications" you run yourself. Because you choose and operate the host, whether your storefront can be licensed and served in mainland China is decided by where you deploy, not by Medusa — a public commercial store served to mainland shoppers needs an ICP filing bound to a licensed mainland host.	Medusa — GitHub README (github.com/medusajs/medusa), retrieved 2026-10-10
You self-host Medusa on a host you choose, and its server keeps your store data in your own database. Medusa's deployment docs say the application "must be deployed to a hosting provider supporting Node.js server deployments" and that "your server connects to a PostgreSQL database, Redis, and other services relevant for your setup" — the customer accounts, carts and orders live in that database. Medusa Cloud is the managed alternative ("Cloud hosts your server, Admin dashboard, database, and Redis instance"), and its documentation names no mainland-China region. Deploy offshore and your mainland shoppers' personal information is held outside China — a cross-border transfer under PIPL (Articles 38–40).	Medusa — Deployment docs (docs.medusajs.com/learn/deployment) & Cloud FAQ (docs.medusajs.com/cloud/faq), retrieved 2026-10-10; PIPL Articles 38–40
For mainland shoppers, the PII a Medusa store collects is a cross-border transfer when the store is hosted offshore. The names, addresses, phone numbers, emails and order history collected at checkout are personal information under China's Personal Information Protection Law; transferring it out of the mainland requires notice, a separate consent distinct from the shopper's agreement to buy (Articles 13 and 23), and a transfer mechanism — a CAC security assessment, the CAC standard contract, or certification (Articles 38–40).	China Personal Information Protection Law (PIPL), Articles 13, 23, 38–40, reviewed 2026-10-10
The storefront needs an ICP filing, and a high-volume handler must store the data in-country. A public storefront served to mainland China carries an ICP filing (备案) duty, and a transactional store generally needs the commercial ICP license (经营许可证) bound to a licensed mainland host; a foreign-hosted storefront cannot be ICP-filed as-is. A critical-information-infrastructure operator or large-volume handler must also store China-collected personal data in the mainland — Cybersecurity Law Article 39 (formerly Article 37) (the 2025 amendment, in force January 1, 2026, renumbered it from 37 to 39, substance unchanged); PIPL Article 40.	21YunBox Compliance Team — China Cybersecurity Law Article 39 (formerly Article 37); PIPL Article 40; State Council Order No. 292; MIIT Order No. 33, reviewed 2026-10-10

Sources verified by the 21YunBox compliance team on 2026-10-10.

For a China-facing store, the deciding question about Medusa is not whether the storefront renders quickly — it is where your customers’ personal information, orders and behavior are allowed to live, whether that storefront can be ICP-filed, and how China payment is settled. Medusa is an open-source digital-commerce platform: its core is licensed under the MIT License and you self-host it on a Node.js host you choose, where the server connects to a PostgreSQL database that holds your customers, carts and orders. A managed option, Medusa Cloud, provisions that infrastructure for you. That self-hostability is the honest lever here — it is what lets you keep China-customer data in-country. Four prongs decide the answer: cross-border transfer of customer PII; the ICP filing the public storefront needs; licensed domestic payment; and in-country storage for a CIIO or high-volume handler.

Medusa's deployment documentation stating that a self-hosted Medusa application is deployed to a Node.js hosting provider you choose, where the server connects to your own PostgreSQL database, with Medusa Cloud offered as the managed alternative — "Your server connects to a PostgreSQL database, Redis, and other services relevant for your setup." Because Medusa is self-hosted on a Node.js host you choose, that database — holding your customers, carts and orders — can sit on mainland infrastructure you control, with Medusa Cloud offered as the managed alternative. Source: Medusa Docs — Deployment

Medusa in China at a glance

What decides it	In Medusa's own terms — and China's law
What you hold	Customer accounts — names, shipping addresses, phone numbers, emails — plus carts, orders and browsing behavior, kept in your Medusa PostgreSQL database. For shoppers in China, all of it is personal information.
Where it runs	Medusa's MIT-licensed core is self-hosted on a Node.js host you choose; Medusa Cloud is the managed alternative, and its documentation names no mainland-China region. Run a China store on an offshore deployment and the customer PII and orders sit offshore — a cross-border transfer under PIPL Articles 38–40 (数据出境).
The ICP-filing door	The storefront is a public internet service in China, which carries an ICP filing (备案) duty; a foreign-hosted storefront on a foreign domain cannot be ICP-filed as-is, so a compliant China store needs an in-country, ICP-filed delivery path.
Payment and residency	Accepting China's mobile wallets runs through a licensed domestic payment path — a regulated non-bank activity a foreign platform cannot provide directly (21YunBox advises here; it holds no payment license). A CIIO or high-volume handler must store the data in-country (Cybersecurity Law Article 39, formerly Article 37; PIPL Article 40).
Reachability is not the axis	Whether the storefront loads is not the question; where the store's data rests, and whether it is lawfully filed and paid, is. The lever: keep customer PII and orders in-country by self-hosting the open-source engine on the mainland, ICP-file the delivery path, and route payment through a licensed domestic provider.

What you actually hold — customer PII, orders and behavior

Medusa describes itself as “a commerce platform with a built-in framework for customization that allows you to build custom commerce applications without reinventing core commerce logic,” and its core commerce modules — customer, cart, order, pricing, inventory, fulfillment — are open-source and run on your own server. That architecture matters for China because it tells you exactly where your most regulated data sits. A Medusa store keeps customer accounts with names, shipping addresses, phone numbers and emails; it keeps the carts and orders those customers place; and it records the behavior behind them. Medusa’s deployment documentation is plain about where that database lives: “Your server connects to a PostgreSQL database, Redis, and other services relevant for your setup.”

The server exposes a public Store API that shoppers’ browsers call and a privileged Admin API your team uses, but both read and write the same database. So the question “where does my customer data live?” has one answer — wherever you deployed the Medusa server. For a store serving mainland-China shoppers, that database is a store of their personal information, and its physical location is a data-residency question. Deploy it offshore and that information is held outside the mainland; self-host it in-country and it stays on the mainland. Medusa hands you that choice; it does not make it for you.

Three doors: cross-border customer data, an ICP-filed storefront, and licensed payment

Cross-border transfer of customer PII. Because the store holds personal information, running a China-facing store on an offshore deployment is a cross-border transfer (数据出境) the moment that data is collected from China. The Personal Information Protection Law puts the duty on the handler — you, the store operator, not Medusa. Articles 38–40 require a clear notice, a separate consent distinct from the shopper’s agreement to buy (Articles 13 and 23), and one lawful transfer mechanism: a CAC security assessment, the CAC standard contract, or certification. If you are a critical information infrastructure operator or you process personal information above the regulators’ volume thresholds — which high-traffic stores routinely cross — the data must also be stored in the mainland, the data-localization duty of the Cybersecurity Law Article 39 (formerly Article 37; the 2025 Cybersecurity Law amendment, in force January 1, 2026, renumbered the data-localization article from 37 to 39, substance unchanged), reinforced by PIPL Article 40.

An ICP-filed storefront. A China-facing storefront is a public internet service, and a public site served to mainland users carries an ICP filing (备案) duty. A transactional store that sells and takes payment is conducting commercial internet information service, which generally calls for the commercial ICP license (经营许可证) bound to a licensed mainland host. A foreign-hosted Medusa storefront on a foreign domain cannot be ICP-filed as-is — so reaching mainland shoppers compliantly means an in-country, ICP-filed delivery path, not simply pointing a foreign storefront at China.

Licensed domestic payment. Accepting China’s dominant mobile wallets means settling through a licensed domestic payment path — a regulated non-bank payment activity that a foreign platform cannot provide directly — and China’s E-Commerce Law layers on further platform and consumer-protection duties. 21YunBox advises on routing payment to a licensed domestic provider; it is not itself a payment licensee.

Reaching the storefront isn’t the question — a compliant in-country store is

Whether the Medusa storefront is reachable from China is not the compliance question; where the store’s customer PII and orders rest, whether the storefront is filed, and how payment settles are. And here Medusa’s license is the opening most teams miss. The core is open-source under the MIT License and fully self-hostable: you deploy it to a Node.js host you choose, and the server “connects to a PostgreSQL database” that you can place on mainland infrastructure you control. The lawful path, then, is to keep China-customer PII and orders in-country by self-hosting the open engine on the mainland — minimizing and pseudonymizing what the store collects so less personal information is at stake — to ICP-file the delivery path in front of it, and to route China payment through a licensed domestic provider. Keeping the data in-country means exactly that: the store’s data stays on a mainland path, never a route that ships it offshore and back.

This is a risk map, not a verdict: whether a localization duty applies, which cross-border mechanism fits, and which ICP track and payment path you need turn on your entity, how much personal information you hold and whose it is — settle the specifics with counsel before you build.

The lawful path — map, localize, deliver

Medusa stays your commerce platform; nothing is rebuilt or migrated. What 21YunBox adds is the compliance and delivery layer around it.

Map. We inventory the customer PII, orders and behavioral data your store holds, where the Medusa server and its database run today, how China payment is handled, whether the storefront is filed, and your consent basis — so the residency, ICP and payment picture is concrete.
Localize. We help you keep China-customer PII and orders in-country by self-hosting the open-source engine on mainland infrastructure, minimize and pseudonymize what the store collects, obtain the Article 13/23 consent, and route China payment through a licensed domestic provider. Localizing means the store data stays on an in-country path.
Deliver. The storefront is a public site that carries an ICP filing duty and needs compliant, in-country delivery — the 21YunBox Optimizer, in front of the stack you already run, with no rebuild.

21YunBox is a compliant overlay and partner, not a competitor to Medusa, and it is advisory on payment licensing. 21YunBox never uses or suggests circumvention of any kind. The goal is simple: your Medusa store runs legally and compliantly for your users in China.

Get a compliance assessment →

Related reading:

Frequently Asked Questions

We already run Medusa — does it just work if we point it at Chinese customers?

Reachability isn't the question. Medusa is software you host, so a store you run from an offshore server is reachable but has no ICP filing — and a public commercial storefront served to mainland shoppers needs one, generally the commercial ICP license (经营许可证), bound to a licensed mainland host. Meanwhile the customer accounts, orders and checkout data Medusa records sit wherever your server is. "We already run Medusa" does not settle the China question; where you host it does.

Is it a problem to sell to mainland China from a Medusa store hosted overseas?

Treat it as a risk to assess with counsel, not a blanket yes or no. Two things follow from hosting offshore: a public storefront served from outside the mainland cannot hold an ICP filing, and the names, addresses, phone numbers and payment details collected at checkout leave the mainland — a cross-border transfer of personal information PIPL governs (notice, separate consent and a transfer mechanism, Articles 38–40). If you are a critical information infrastructure operator or a large-volume handler, that data may have to be stored in China (Cybersecurity Law Article 39 (formerly Article 37); PIPL Article 40), and China payment must settle through a licensed domestic path.

Can 21YunBox help make our Medusa store work in China?

Yes. Because Medusa is open-source and self-hostable, we help you keep customer PII and orders in-country by running the engine on mainland infrastructure, map your PIPL cross-border and data-residency exposure for your entity and your shoppers, and stand up ICP-filed, in-country delivery in front of the Medusa store you already run — no rebuild, no second codebase — while advising on routing China payment through a licensed domestic provider. Get in touch to work through your specific case.