Skip to content

Request a theme integration

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

POST/account/theme_integrations

Costs 2 rate-limit points · Rate limits

Request a theme integration, as the page editors' Request setup button does: Quick Buy (the 'Notify me'/'Preorder' button inside the theme's quick add popup) on the home, collection or search page, or Featured products (the button on featured product sections) on the home page. Our team sets it up for the theme, usually within 12-24 hours, and tells the merchant by email or chat. Paid plans only.

type is quick_buy or featured_product. page is home, collection or search for quick_buy and home for featured_product. Returns the new row with enabled null; read it back with GET /account/theme_integrations/:id. A page that already has one is 409.

Also searched asrequest quick buyset up quick buyrequest quick add integrationrequest featured product integrationset up featured productsrequest setup

Headers

  • Idempotency-Keystring

    A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • typestringRequired

    Which integration to request, quick_buy (the button in the theme's quick add popup) or featured_product (the button on featured product sections).

    One of quick_buyfeatured_product
  • pagestringRequired

    The page to set it up on, home, collection or search for quick_buy and home for featured_product.

    One of collectionhomesearch

Returns

The theme integration object.

Errors

403
forbidden

The credential is valid, but the store's plan or settings do not allow this operation.

403
plan_required

The change uses a feature that is only available on a paid STOQ plan. Connecting a paid-only integration returns 403; a write that sets paid-only fields returns 422 and saves nothing.

409
conflict

The request is well formed, but the resource's current state does not allow it.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

One or more fields failed the action's schema.

422
validation_failed

The request failed validation.

Any request can also fail with auth_invalid (401) or rate_limited (429).

Every error has the same shape: see Errors and the list of error codes.

POST/account/theme_integrations
curl -X POST "https://app.stoqapp.com/api/v2/external/account/theme_integrations" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "quick_buy",
    "page": "collection"
  }'
Response
{
  "id": "9c1f4e2a-6b3d-4a8e-b7f0-2d5c8e1a4b6f",
  "type": "quick_buy",
  "pages": [
    "collection"
  ],
  "enabled": null
}