Skip to main content

Create Instance

POST 
/api/storefront/instances

Create an instance from a key pasted in by hand — the break-glass alternative to the store's owner-approval flow (Start Store Connection). Creates the instance, its sales channel and its default sync controls, then probes the store once so the dashboard can name it. A failed probe never blocks creation; the failure surfaces afterwards as connection_error on the instance. The key is stored encrypted and never returned.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Body — every field:

  • name (required, string, max 255) — unique across EVERY integration on the tenant, not just Storefront.
  • store_url (required, string, max 255) — valid URL and a bare origin: scheme + host (+ port), no path, query, fragment or credentials; https unless the host is local (localhost, 127.0.0.1, *.localhost, *.test). Everything downstream appends the Store API path to it, so a pasted admin URL would build a base that 404s every call.
  • api_key (required, string, min 8, max 255).
  • order_import_start_date (required, Y-m-d) — orders placed before this date are never imported. Must be on or after the tenant's inventory start date, otherwise 422 Date must be on or after inventory start date (m/d/Y).
  • store_id (optional, nullable, integer) — must reference an existing store. The sales channel is filed under it; when omitted the lowest-numbered store is used.
  • product_pricing_tier_id (optional, nullable, integer) — must reference an existing pricing level. The level the product push prices from. Stored as pricing.pricingTier, and a level supplied with no master stated also sets pricing.masterOfPrice to sku.io.
  • compare_at_pricing_tier_id (optional, nullable, integer) — must reference an existing pricing level and must differ from product_pricing_tier_id. Sent to the store as the compare-at price. Stored as pricing.compareAtPricingTier.
  • push_products (optional, boolean) — default false.
  • low_stock_threshold (optional, nullable, integer, min 0) — default 0.
  • is_automatic_sync_enabled (optional, boolean) — default true.
  • require_mapped_products_for_sales_order (optional, boolean) — default false. When true, the automatic paths hold any store order carrying a line whose SKU has no mapped product; the order reads as Held on the orders list and its sales order is created once the products are mapped. A user-initiated Create SKU Orders ignores the hold by design.

Not accepted here: pricing, inventory, auto_create_products and notify_customer_on_fulfillment are Update Instance fields. Unrecognised keys are ignored rather than stored.

Permission: integrations.update.

Authentication: Bearer token (session or PAT).

Request​

Responses​

OK

Response Headers
    Content-Type