Developer API

Choose the right access.

Plans are billed in USD with a 14-day trial and no usage charges. Technical request limits still apply. View all plan features.

1. Open SwatchBro → Developer API in your Shopify admin.
2. Create a named key. Use audit-only access unless the integration needs Enterprise repairs.
3. Save the secret when displayed; it is shown only once. Store it in your backend’s secret manager or protected environment.
4. Send it in the Authorization: Bearer header over HTTPS. Revoke unused or compromised keys in the app.

Never put a key in Liquid, theme JavaScript, browser bundles, mobile apps, source control, URLs, screenshots, or logs. SwatchBro’s Shopify access token is never returned to your integration. The verified key determines the merchant; requests do not accept a caller-selected shop or tenant.

Production base URL: https://swatchbro.brofam.app. Use keys created in the public SwatchBro installation. Development keys and endpoints are separate.

Scan and preview missing images.

Send Shopify product GIDs from your own catalog integration in batches of 1–50 unique products. Use the option names your store actually uses; the default is Color/Colour. Scan and preview currently return the same read-only repair plan.

POST /external/v1/variant-images/scan

Audit missing variant-image coverage.

POST /external/v1/variant-images/preview

Review matches and obtain the revision required for apply.

Set SWATCHBRO_API_KEY securely in the server environment before running this example. Product ID 123 is a placeholder—replace it with a real product GID from your store.

curl --request POST \
  'https://swatchbro.brofam.app/external/v1/variant-images/preview' \
  --header "Authorization: Bearer $SWATCHBRO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"productIds":["gid://shopify/Product/123"],"optionNames":["Color","Colour"]}'

A successful response includes productsScanned, missingVariants, readyRepairs, ambiguousGroups, a revision, and rows. Each row identifies the product, option value, missing variant GIDs, proposed media, match classification, and writable status.

Only groups with missing assignments appear in the report. A successful response is not proof that every supplied product exists: check the returned products and rows against the batch you requested.

Review first. Apply deliberately.

Enterprise writes require a write-enabled key, explicit confirmation, and the unchanged preview revision. Review the whole preview: apply processes all eligible rows in the requested batch, not a caller-selected subset of preview rows. To narrow the batch, request and review a new preview.

curl --request POST \
  'https://swatchbro.brofam.app/external/v1/variant-images/apply' \
  --header "Authorization: Bearer $SWATCHBRO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: catalog-repair-20260927-001' \
  --data '{"productIds":["gid://shopify/Product/123"],"optionNames":["Color","Colour"],"revision":"REVISION_FROM_PREVIEW","confirmed":true}'

Replace REVISION_FROM_PREVIEW with the actual returned revision. Keep the same product IDs and option names. The server rescans before writing and rejects a changed preview.

Repairs append existing Shopify product media to variants with no media. They do not upload new images, replace existing variant images, change inventory, prices, options, or product publication, or proxy image delivery. CSV image ingestion is a separate merchant-reviewed workflow.

Successful apply returns productsUpdated, variantsUpdated, and revision. Verify the affected assignments in Shopify. Multi-product repairs are not a single atomic transaction: if a timeout or failure occurs, inspect current assignments and request a fresh preview before attempting remaining repairs.

Use a unique 16–128 character Idempotency-Key containing letters, digits, periods, underscores, colons, or hyphens. Within the receipt window, the same key and identical request return the recorded result; different input with the same key is rejected. Do not create a new key merely to bypass an operation still in progress.

Keep jobs bounded.

• Request body: up to 64 KiB; 1–50 unique Shopify product GIDs per request.
• Scan and preview: up to 10 accepted requests per key per minute for each operation.
• Apply: up to 2 accepted requests per key per minute.
• Variant scanning paginates in batches of 250, up to 2,250 variants per product. Products with more than 250 product-media items are not supported by this repair endpoint.
• Idempotency receipts are retained for 24 hours; the recent-activity view lists the latest 50 successful API requests.

Process batches sequentially, checkpoint results, and use bounded retries with backoff. Shopify throttling and execution limits can require smaller batches. These ceilings are safeguards, not a throughput guarantee. API responses use Cache-Control: no-store; do not cache responses in shared public caches.

Handle errors without blind retries.

For validation errors, unexpected responses, timeouts, or failed writes, stop and inspect the result. Do not automatically replay an entire repair batch. Contact BroFam support with a sanitized error and request time—never a key or access token.

Build an audit, not a storefront dependency.

This API is useful for a merchant custom app, PIM, scheduled catalog audit, or controlled repair service. Keep product pages and swatch interactions on Shopify-native data and Shopify-hosted images; no Developer API request is needed for every page render or color click.

Explore SwatchBro · Ask an integration question