Channels

A Channel is one user-owned fulfillment destination. A ChannelPlatform describes how Openship searches the destination catalog, retrieves one item, creates or cancels a downstream purchase, registers provider webhooks, and interprets tracking or cancellation events.

Current model boundary

Channel belongs directly to one Openship user and references one ChannelPlatform. It holds destination identity, domain, access/refresh token fields, expiry, metadata, channel items, links, and cart items. ChannelPlatform stores operation selectors and OAuth configuration.

Match connects a shop item/variant to one channel item/variant. CartItem records the selected downstream line, and TrackingDetail records tracking facts propagated through the routing path. The upstream shop and downstream provider remain authoritative for their own inventory, orders, funds, and shipment state.

Channel ownership is user-scoped. Every operation must also validate ownership of the linked shop, order, match, cart item, and channel item; selecting a related ID must not move data across users.

Compiled adapters and custom execution

Current files under features/integrations/channel provide Shopify and Openfront handlers plus an executor. The operation family includes channel product search/detail, purchase creation/cancellation, webhook management, and tracking interpretation.

The executor can also call a database-selected HTTP URL or dynamic function path. Treat that as privileged code/network configuration. Restrict destinations, prevent private-address and redirect escapes, cap time/body size, validate request and response schemas, isolate credentials, and use stable provider idempotency keys. The current configurable path is not a general secure 3PL connector by itself.

Routing workflow

1. Configure a synthetic Shop and ShopPlatform.
2. Open /dashboard/platform/channels and configure a ChannelPlatform tied to an implemented test adapter.
3. Create a user-owned Channel with sandbox credentials.
4. Use channel product search/detail to identify a candidate variant.
5. Open /dashboard/platform/matches and match the shop line to that exact channel item.
6. Link the shop and channel, then route a synthetic order through matchOrder, cart commands, and createChannelPurchase/placeOrders as required by the current schema.
7. Record downstream purchase identity and test tracking/cancellation callbacks.
8. Reconcile Openship, shop, and channel state after success, duplicate delivery, timeout, partial failure, and cancellation.

There is no current channel-onboarding mutation or demo seed. The docs site's POST-only demo endpoints return in-memory synthetic payloads for adapter development; they are not a fulfillment provider, durable order store, invoice service, or live 3PL.

Controlled GraphQL boundary

Current custom operations include searchChannelProducts, getChannelProduct, createChannelPurchase, cancelPurchase, channel webhook management, matching queries/commands, addToCart, addMatchToCart, and placeOrders. Handler support differs by adapter, so inspect schema.graphql and the selected implementation together.

Do not use generated CRUD to mark a purchase fulfilled or tracking complete when an external effect has not been authenticated and reconciled. Preserve the provider event ID, route ownership, bounded status/error evidence, and immutable shop/channel item identities.

Current limitations

Current source does not establish WooCommerce, BigCommerce, Amazon, email, spreadsheet, generic 3PL, or carrier integrations. It does not provide payment settlement, warehouse inventory authority, durable retry for every webhook path, or proof that arbitrary configured HTTP endpoints are safe. Channel credential fields also require a deployment-specific encryption and field-access review.

One current cancellation handler queries a CartItem.title field while the registered model defines CartItem.name; verify and repair that route in the owning Openship source before relying on channel cancellation. Also test webhook raw-body signatures, replay IDs, asynchronous failure persistence, token redaction, cross-user IDs, duplicate purchases, cancellation after partial fulfillment, and tracking reconciliation.

See Product matching and Create a custom channel integration.