Core concepts

The Foundry data model and how inventory, catalog, and order data flow through it.

Foundry sits between your suppliers and your sales channels: supplier feeds come in, a unified catalog lives in the middle, and listings, inventory, and orders sync out to wherever you sell. Every API object hangs off this model, so it’s worth ten minutes before you build.

The data model

The relationship that makes Foundry work: a Variant can be linked to many ChannelSkus. The supplier’s row for part TC-1042 and your BigCommerce listing for the same part both point at one variant, which is why a cost change on the supplier side can flow to a price update on the storefront.

Product types

• SIMPLE — one product, one variant.
• FAMILY — one product with multiple variants (size/color/fitment options). Option values live on each variant.
• BUNDLE — a product sold as a set of other variants.
• ASSEMBLY — a product built from a bill of materials via work orders.

How data flows in

1. An inbound channel imports SKUs (CSV upload, scheduled FTP/SFTP pull, vendor SFTP push, or Google Sheets).
2. Each row lands as a ChannelSku with no variant link — “unmapped”.
3. Unmapped SKUs get resolved two ways:
   • Link — attach the ChannelSku to an existing variant.
   • Promote — create a new product/variant from one or more ChannelSkus.
4. Once linked, the feed keeps the variant’s cost and supplier quantity current on every import.

Bulk imports signal completion with the import.completed webhook event rather than firing per-row events — see Webhook events.

How data flows out

Outbound channels hold a ChannelSku per listing. Foundry pushes inventory (and optionally price, via per-channel pricing formulas) to connected platforms when availability changes, and pulls orders back in. Headless storefronts skip the push entirely — they read the catalog live through the Storefront API.

Inventory and availability

Three numbers matter per variant:

• On hand — physical stock across warehouses.
• Reserved — quantity held by open orders (reservations are created when an order lands and released when it ships or cancels).
• Available = on hand − reserved. This is what channels receive and what the inventory.availability_changed webhook reports.

Variants can also be untracked (made-to-order): they report as in stock without a quantity.

Orders and fulfillment

Orders enter from outbound channels (platform webhooks or the Storefront API — there is no admin-side order creation). Each order line reserves stock, and fulfillment produces shipments carrying carrier and tracking data. Stocked lines ship from your warehouse; drop-ship lines generate purchase orders to the supplier. Order lifecycle transitions fire order.status_changed, and shipment creation fires order.shipped.

Purchasing

Purchase orders go to suppliers (inbound channels), move through DRAFT → SUBMITTED → ... → RECEIVED, and receiving them adjusts stock. Vendor invoices are recorded against POs for reconciliation. The purchase_order.status_changed event with toStatus: "RECEIVED" is the goods-received moment most accounting integrations care about.

Which API do I need?

• Partner API — back-office access with an admin fims_* key: catalog reads/writes, orders, purchase orders, stock, webhook management. Use this for accounting sync, EDI, analytics, and custom tooling.
• Storefront API — channel-scoped, safe-for-frontend access with a fims_sf_* key: catalog browsing, inventory checks, order submission. Use this to build your own storefront.
• Webhooks — signed HTTPS callbacks from either surface, so you react to changes instead of polling.