Skip to main content

Create Faire Instance

POST 
/api/faire/instances

Create a new Faire integration instance.

Not yet available to API tokens

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

Required Fields:

  • name - Display name for this instance (max 255 chars)
  • fulfillment_mode - fbm (fulfilled by merchant) or fbf (fulfilled by Faire)

Optional Fields:

  • order_import_start_date - Only import orders placed on or after this date (YYYY-MM-DD). Interpreted in the account timezone: the boundary is local midnight on that day, so an order placed the evening before is not imported.

Fulfilled by Faire (FBF) instances: Creating an fbf instance automatically provisions a dedicated "FBF" warehouse for the instance. Faire-fulfilled orders deduct stock from that warehouse; record inbound stock to Faire's fulfillment center with a warehouse transfer to it.

OAuth Authorization: After creation, the instance is unauthorized (is_authorized: false). The frontend must:

  1. Call GET /api/faire/instances/{id}/authorization-url to obtain the Faire OAuth redirect URL.
  2. Redirect the user (who must be a Faire brand admin) to that URL.
  3. Faire redirects back to GET /faire/callback, which exchanges the authorization code for a long-lived access token and persists it.

Response: Returns the created integration instance with is_authorized: false and granted_scopes: [].

Instance names must be unique name must be unique across every integration instance in the account, not just Faire ones. Reusing a name that is already taken returns 422 with a name error — it does not create a second instance.

Request​

Responses​

Created

Response Headers
    Content-Type