Openship order routing and fulfillment setup

Where Openship fits in the fulfillment stack

Openship addresses the gap between accepting an order somewhere and fulfilling it elsewhere. It is intended for merchants, 3PL operators, marketplaces, and teams whose inventory or fulfillment process spans several systems. A seller might receive an order in Shopify or WooCommerce, then send it to a supplier's Shopify store, a fulfillment partner, a Google Sheet, an email recipient, or a webhook endpoint.

The central design separates the origin of an order from the place that handles it. According to the README, shops represent stores where customers purchase. Channels represent destinations that process those orders. Links connect a shop to a channel, while product-level matches determine whether a particular shop product should be processed through that channel. This model is more specific than a general connector list because fulfillment depends on the relationship between catalog items, not just on receiving the order.

Openship is therefore not presented as a storefront, warehouse management system, or carrier-tracking application. It sits between those systems and governs where order data goes. That boundary matters. A team looking for inventory forecasting, warehouse picking interfaces, or parcel tracking may need another component even if Openship can route an order into its API.

Shop, channel, link, and match routing model

The documented order path begins with a connected shop. New orders from that source can enter Openship and become candidates for routing. A channel then identifies a fulfillment destination. Linking the shop and channel establishes the general path, but a product match provides finer control by associating a shop product with a channel product.

This separates connectivity from catalog policy. An integration can technically receive orders without every item being eligible for a particular destination. Product and variant-level matching allows the operator to decide which shop products correspond to supplier products. The README also lists bulk matching, rules, and exceptions, although it does not provide a detailed rule syntax or examples.

The application exposes this work through a dashboard and a GraphQL API. The README describes automatic routing, synchronization, status tracking, error handling, and retries as key capabilities. It does not explain the internal queue, retry schedule, idempotency policy, or failure queue. Those omissions matter for an adoption decision. An order router can be technically simple when every destination accepts orders, but production behavior depends on what happens after a timeout, duplicate webhook, mapping change, partial fulfillment, or unavailable fulfillment partner.

Next.js, KeystoneJS, GraphQL, and PostgreSQL architecture

Based on the repository layout, Openship is a full-stack TypeScript application rather than a small webhook library. The frontend uses Next.js 15 with the App Router. The backend uses KeystoneJS 6 and exposes a GraphQL API. PostgreSQL is the system of record, accessed through Prisma ORM.

The `app/` directory contains dashboard routes, storefront routes, API endpoints, and webhooks. Backend models and the GraphQL schema live under `features/keystone/`, administrative platform code appears under `features/platform/`, customer-facing code under `features/storefront/`, and integrations under `features/integrations/`. Shared interface components are outside those feature areas in `components/`.

Authentication is documented as session based with role-based permissions. The initialization flow directs the first administrator to `/init`. This makes Openship more than a routing worker: it also includes an administrative interface and an API surface. That also expands the operational surface. Database migrations run as part of development and production builds, while deployment must account for the GraphQL endpoint, application routes, secrets, and persistent PostgreSQL storage.

Installing Openship and starting the development stack

The documented prerequisites are Node.js 20 or later, PostgreSQL, and one of npm, yarn, pnpm, or bun. The following setup uses npm, matching the repository's lockfile and package scripts. Clone the project, enter its directory, and install dependencies:

git clone https://github.com/openship-org/openship.git
cd openship
npm install

The README instructs users to copy the example environment file. The top-level repository entries do not list `.env.example`, so a checkout should be checked for that file before this command is treated as guaranteed.

cp .env.example .env

The required database value follows the documented PostgreSQL form. The session secret must contain at least 32 characters. Integration variables depend on the connectors being enabled:

DATABASE_URL="postgresql://username:password@localhost:5432/openship"
SESSION_SECRET="your-very-long-session-secret-key-here-32-chars-minimum"
SHOPIFY_APP_KEY="your-shopify-app-key"
SHOPIFY_APP_SECRET="your-shopify-app-secret"
SHIPPO_API_KEY="shippo_test_..."

Start the development process with the repository's documented command. It builds the KeystoneJS schema, deploys existing database migrations, and starts Next.js:

npm run dev

Open `http://localhost:3000` for the dashboard or `http://localhost:3000/api/graphql` for the API explorer. On the first dashboard visit, Openship prompts the operator to create an administrator at `/init`. After that, the practical first workflow is to connect one shop and one channel, create the required product matches, and inspect routing behavior before adding production credentials.

Integration choices and their undocumented details

The README names Shopify and WooCommerce as shop sources and also states that custom API connectors and webhooks are possible. Shopify, 3PL services, email, Google Sheets, webhooks, and dropshipping destinations are listed as possible channels. Shippo is represented in the environment configuration through `SHIPPO_API_KEY`, although the integration scope for that key is not described in the setup text.

Native Shopify credentials alone do not establish that an installation is ready for production order import. The README does not provide callback routes, required OAuth scopes, webhook topics, or synchronization settings for the Shopify connector. It also does not specify the authentication method for WooCommerce or the exact payload expected by a custom channel. Those details may exist elsewhere in project documentation, but this README does not establish them.

The distinction between advertised support and a turnkey connector is important here. Openship's model can accommodate many destinations, but “custom channels” still require code, an agreed payload, authentication decisions, and error handling. The repository's topic list includes Netlify and Vercel, and the README provides deployment links for those platforms and Railway, but the deployment text does not enumerate required production environment variables or operational settings.

Failure modes and the cost of owning the router

The clearest failure mode is a bad or missing product match. A shop may be connected successfully while its items have no corresponding channel products, so automatic processing cannot occur as intended. Variant-level errors are especially consequential in commerce because a plausible match at the product level does not guarantee the correct size, color, or other option. The README lists variant matching and exceptions but does not publish validation rules, so operators must verify those mappings against representative orders.

Another limitation is operational ownership. The repository includes development and production build scripts, migrations, an API, authentication, and integrations. Operators therefore need to account for database availability, secret rotation, application upgrades, and connector behavior. The `build` script builds KeystoneJS, runs migrations, and creates a Next.js production build, which means deployment is coupled to database migration access.

Openship uses the AGPL-3.0 license. That identifier matters to organizations reviewing how modified source code is distributed or made available in connection with the licensed software. This is not legal advice, and the README does not summarize the license obligations. The applicable license text should be reviewed directly before embedding Openship in a hosted or redistributed product.

Direct fulfillment versus Openship routing

A real alternative is direct fulfillment from the sales platform to the supplier or 3PL. In that model, Shopify, WooCommerce, or another commerce system sends the order directly, without an intermediary that models shops, channels, links, and product matches. This approach has fewer moving pieces when there is one source, one destination, and a stable integration between them.

Openship takes a different approach. It centralizes the routing relationship and adds product-level or variant-level matching. That is useful when the catalog presented to customers differs from the catalog available at the supplier, when orders need to reach several kinds of destinations, or when email, spreadsheets, and webhooks need to participate in fulfillment workflows. The trade-off is additional infrastructure: PostgreSQL, a Next.js application, KeystoneJS, GraphQL, sessions, migrations, and connector configuration.

For a small merchant with a straightforward supplier relationship, the direct path may be easier to reason about. For a multi-channel operation, Openship's explicit routing model is the reason to consider adoption. The deciding evidence should come from a small mapping test using real variants, not from the list of supported integrations alone.

Maintenance activity and upgrade implications

The repository is not archived, and its last push was on 2026-08-25. That indicates recent repository activity, but release history is much less frequent. The listed releases are v3.0 on 2024-10-01 and v.2.0.0 on 2022-08-10, while `package.json` reports version `3.0.0`.

Upgrade cost appears tied to the stack rather than to a small client library. A deployment runs KeystoneJS schema generation and Prisma migration commands before starting or building Next.js. Changes to database models or migrations therefore require a compatible PostgreSQL procedure and a rollback plan. The README does not document rollback, deployment health checks, supported upgrade paths, or a release cadence.

An adopting organization should first verify the exact version being deployed against its migration history. It should also review the AGPL-3.0 file directly and confirm that its hosting and distribution model is acceptable. Repository activity alone does not answer those operational questions.

Editorial conclusion

Openship suits merchants or fulfillment operators that need orders and product mappings routed through a central, customizable system. It is a poor fit for a single-store operation whose provider already handles the required fulfillment flow, or for operators unwilling to maintain PostgreSQL, session security, migrations, and connector credentials. Verify first that your sales platform and destination are supported by the available integrations, confirm that the required environment variables can be supplied, and test variant-level matching before connecting production orders.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. openshiporg/openship on GitHub
3. Project website
4. README
5. Releases