Create connect

POST

/account/integrations/{id}/connect

curl --request POST \
  --url https://app.stoqapp.com/api/v2/external/account/integrations/example/connect \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <X-Auth-Token>' \
  --data '{ "api_key": "string", "list_id": "string", "reconnect": "string", "account": 5 }'

• Production

Connect an integration. OAuth integrations (klaviyo, judgeme, smile, gorgias) return 201 with connect_url, a one-use link (15 minutes) to the dashboard panel where the merchant presses Connect and approves in the provider. Show it to the user; do not open or fetch it. API-key integrations (postscript, omnisend, mailchimp) take api_key, check it with the provider where STOQ can (Postscript, Mailchimp) and save it. Over MCP or the in-app assistant they take no key and return 201 with key_url instead: API keys are entered by the merchant in STOQ. Show key_url to the user; do not ask for the key.

Note: Read GET /account/integrations/:id afterwards for the result. Switch integrations (shopify_flow, meta_pixel, split_order, shopify_customers) have nothing to connect: turn them on with PATCH /account/integrations. reconnect true replaces a connection or key that is already there. A new link replaces the last one; 5 links per integration an hour.

Authorizations

• ApiKeyAuth

Parameters

Path Parameters

id

required

string

Request Body^required

Media typeapplication/json

object

api_key

list_id

reconnect

account

Example

{
  "api_key": "string",
  "list_id": "string",
  "reconnect": "string",
  "account": 5
}

Responses

200

Success — the updated resource.

Media typeapplication/json

object

Example ^generated

{}

202

Accepted — async/bulk work was queued. Poll the returned job.

Media typeapplication/json

Returned for async/bulk work — poll the job until it reaches a terminal state.

object

job_id

string

status_url

string

Example

{
  "job_id": "job_a1b2c3",
  "status_url": "/api/v2/external/jobs/job_a1b2c3"
}

401

Missing or invalid X-Auth-Token.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Unauthorized"
  ]
}

404

The resource does not exist for this shop, or the action path is not registered.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Offer not found"
  ]
}

422

The request failed validation.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "name is required"
  ]
}

429

Rate limited — cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Rate limit exceeded"
  ]
}