Concepts

This page covers the building blocks of Storlaunch: what each object is, how they relate to each other, and the lifecycle they go through. Read this before you go deep on any specific feature — the rest of the docs assume you know what a storefront is and how it differs from a workspace.

The data model

Workspace
  ├── Storefronts
  │     └── Custom domains
  ├── Products
  │     ├── Variants
  │     ├── Product files       (digital products)
  │     └── Inventory levels    (physical products)
  ├── Customers (buyers)
  │     └── Addresses
  ├── Carts        ─────→ Orders
  ├── Orders
  │     ├── Order items
  │     ├── Fulfilments         (→ Fulkruma)
  │     ├── Deliveries          (digital delivery links / licenses)
  │     ├── Invoices            (→ Plugipay)
  │     └── Refunds
  ├── Webhooks
  ├── API keys
  └── Team members

Everything is scoped to a workspace. Cross-workspace queries don't exist — if you operate two brands, you'll have two workspaces and treat them as fully separate.

Workspace

A workspace is the top-level tenant boundary. Each workspace has:

Its own storefronts, products, orders, customers
Its own API keys
Its own team members and roles
Its own webhook endpoints
Its own linked Plugipay (for payments) and Fulkruma (for fulfilment) workspaces, auto-provisioned on first use

Workspaces are isolated. Data never crosses between them.

You can be a member of multiple workspaces with different roles in each. Switching is done via the top-left workspace switcher in the dashboard.

Identifier: acc_01H… (26-char ULID prefixed by type).

Storefront

A storefront is the public-facing shop — the URL buyers visit, the theme they see, the policies that apply.

A storefront has:

A name and subdomain (your-shop.storlaunch.forjio.com)
An optional custom domain
A theme (colors, typography, layout)
A currency for display
Policies (returns, shipping, terms)
A linked product catalog (products are workspace-scoped, but a storefront can optionally filter to a subset)

A workspace can have multiple storefronts — useful for serving different markets or brands from the same back office.

Product

A product is something you sell. The same Product shape covers physical and digital goods; a type field selects the behavior.

A product has:

A name and slug
A description (markdown)
A price and currency
A type: physical or digital
Optional variants (size, color, format)
Optional product files (for digital delivery)
Optional inventory levels (for physical fulfilment)
A published flag — unpublished products are dashboard-only
Metadata (up to 50 key-value pairs)

Identifier: prod_01H….

Variant

A variant is a specific purchasable form of a product. The default product has one implicit variant; adding variants splits inventory, pricing, and SKUs.

A variant has:

A name (e.g., "Medium / Red")
An optional SKU
A price (overrides the parent product's price)
Inventory tracking flags
Option values (the size/color combination it represents)

Identifier: variant_01H….

Cart

A cart is a pre-checkout collection of items belonging to a buyer (anonymous or signed-in). Carts have a TTL — abandoned ones expire and trigger recovery emails via Ripllo.

A cart has:

A reference to the storefront
A list of cart items (each pointing to a product + variant + quantity)
An optional customer reference (if the buyer is signed in)
Optional discount codes applied
A computed subtotal and total (server-side; never trust client math)

Identifier: cart_01H….

Order

An order is what a cart becomes when it succeeds at checkout. It's the durable record of the transaction.

An order has:

A reference to the storefront and the buyer customer
A snapshot of the items (frozen at purchase time, even if the product changes later)
A shipping address (physical) or delivery email (digital)
A status (see below)
A payment status (pending, paid, failed, refunded)
A fulfilment status (unfulfilled, partial, fulfilled, delivered)
A reference to the Plugipay checkout session that paid for it
A reference to any Fulkruma fulfilment(s) that shipped it

Identifier: order_01H….

Order status transitions:

State	Means
`pending`	Buyer submitted; awaiting payment confirmation
`paid`	Plugipay confirmed payment; ready to fulfil
`fulfilled`	Items shipped (physical) or delivered (digital)
`canceled`	Pre-payment cancellation by buyer or merchant
`refunded`	Post-payment reversal; funds returned

Storlaunch advances an order's status as the underlying events (Plugipay webhook, Fulkruma webhook, manual action) arrive.

Customer (buyer)

A customer in Storlaunch is the buyer-side identity — the person placing orders on a storefront. It is not the merchant; the merchant is a workspace member.

A customer has:

An email (primary key per workspace)
An optional name and phone
A list of saved addresses
A list of past orders
An optional Huudis identity (if they signed up via SSO)

Identifier: cust_01H….

The same email across two of your workspaces is two separate customer records — we don't unify across tenants.

Fulfilment

A fulfilment is the act of getting a paid order to the buyer. Behavior differs by product type:

Physical products — we emit a product.created / order.fulfilment.requested event into Fulkruma, which handles picking, packing, label generation, and courier handoff. Fulkruma pushes status webhooks back as the shipment moves.
Digital products — Storlaunch generates a signed download link or license key and emails it to the buyer. We track delivery attempts and link clicks on the order.

A single order can mix product types — we create one fulfilment per type.

Delivery (digital)

A delivery is the record of a digital fulfilment. Each delivery has:

A reference to the order item
A signed, time-limited download URL (or a generated license key)
An expiry (default 7 days)
A maximum activation count (for license keys)
A history of access attempts

Identifier: del_01H….

API key

An API key authenticates server-to-server calls. Keys have:

An identifier (pk_test_…, pk_live_…, sk_test_…, or sk_live_…)
A role: publishable (read-only public data) or secret (full account access)
A creation date and last-used timestamp

Keys are per-workspace. They authenticate via a simple Authorization: Bearer <key> header — see API → Authentication.

Test vs live

Storlaunch maintains separate, parallel data sets for test and live:

Test API keys start with _test_; live with _live_.
Storefronts, products, orders, customers created with test keys are visible only to test mode.
The portal has a test/live toggle. Data and counts switch.

You can run both side-by-side — production code uses live keys, your local dev uses test keys.

Identifiers (the prefix system)

Every Storlaunch object has a typed prefix on its ID:

Prefix	Type
`acc_`	Workspace (account)
`prod_`	Product
`variant_`	Product variant
`cart_`	Cart
`order_`	Order
`cust_`	Customer (buyer)
`del_`	Delivery
`pk_` / `sk_`	API key (publishable / secret)
`whep_`	Webhook endpoint
`evt_`	Webhook event

The suffix is a ULID — sortable by creation time, globally unique.

How the family fits

When you place an order in Storlaunch, three services collaborate:

Storlaunch owns the storefront, the catalog, the cart, the order.
Plugipay owns the checkout session, the payment, the invoice. Storlaunch passes the cart total to Plugipay and listens for the payment.succeeded webhook.
Fulkruma owns the shipment (physical orders only). Storlaunch emits a fulfilment-requested event and listens for status updates.
Ripllo owns marketing surfaces — discount codes, abandoned-cart, referrals, blog — embedded inside the Storlaunch dashboard via a proxy.

You don't have to think about this when using Storlaunch; we handle the orchestration. But understanding the split helps when you're reading webhooks: a payment.succeeded event has a Plugipay shape, an order.created event has a Storlaunch shape.

Portal tour — the dashboard, feature by feature.
API reference — every endpoint.
Authentication overview — how sign-in works.