Instances

An Instance is a workspace inside an Organization - the scope your catalog and product data live in. An organization can own several instances (for example one per brand, market or environment), each isolated from the others.

Every instance has a human-readable name and a stable, URL-safe handle. The handle is the instance’s permanent identifier and doubles as the tenant in product service hostnames: the Product Management API for an instance with handle acme-eu lives at https://acme-eu.product-management.flowkiwi.net, scoped further to an organization through the X-Flowkiwi-Organization-Id header.

The Instance object

Property	Type	Required	Description
id	string | null	-	Unique identifier of the instance.
name	string | null	-	Human-readable display name of the instance.
handle	string | null	-	Stable, URL-safe identifier of the instance. Used as the tenant subdomain when addressing the per-instance product services (e.g. https://acme-eu.product-management.flowkiwi.net). Lowercase letters and hyphens only, no leading or trailing hyphen, unique across all instances.
created_at	string | null	-	Date and time the instance was created (ISO 8601, UTC).
updated_at	string | null	-	Date and time the instance was last updated (ISO 8601, UTC).
organization_id	string | null	-	Identifier of the organization that currently owns the instance.
created_by_organization_id	string | null	-	Identifier of the organization that originally created the instance. Immutable, it does not change when the instance is transferred to another organization.

How organizations, instances and product data fit together

1. A partner creates an Organization and becomes its owner.
2. The organization owner creates one or more instances - POST /organizations/{organizationId}/instances.
3. Product data (products, variants, options…) is then read and written against that instance through the Product Management API, scoped by the organization header.

Common workflows

• Spin up a new workspace. POST /organizations/{organizationId}/instances with a name and a handle. The handle must be unique and is fixed for the life of the instance.
• Rename without breaking integrations. PATCH changes the display name only; the handle never changes, so existing integrations keep working.
• Hand an instance to another organization. POST .../transfer moves ownership of an instance to a different organization.

Conventions

Authentication

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

Identity is platform-scoped: there is no X-Flowkiwi-Organization-Id header. The target organization is taken from the {organizationId} path parameter, and ownership checks are enforced against the partner identity in your token.

Partial updates

PATCH uses JSON Merge Patch with Content-Type: application/merge-patch+json.