HTTP API

Smart Collection Pro has an HTTP API for working with your Managed Collections from outside the app: creating them, reading them back, updating their conditions, or removing them. It's meant for stores that want to drive collections from their own systems, whether that's a custom admin tool, a migration script, or another app in your stack.

It's Opt-In

The API is off by default, and we turn it on store by store rather than exposing it to everyone automatically. Two reasons for that:

• Fit. The API is still young, and we'd rather walk through what you're trying to build first, so we can tell you honestly whether it's a good match today or whether you're better served waiting for something we haven't shipped yet.
• Security. An API key is external access to your store's collections. We want to make sure it's set up safely from day one, keys scoped sensibly, stored properly on your end, revoked when they're no longer needed, rather than handed out and forgotten.

Get in touch with our team when you're ready to start. We'll talk through your use case, enable the API for your store, and help you take your first steps: that includes sending you our OpenAPI schema and example code, so you're not reverse-engineering the API from scratch.

API Keys

Once enabled, you can generate API keys yourself under Smart Collection Pro → Settings → API. Each store can have up to five active keys at a time, so you can, for example, use a separate key per integration and revoke one without affecting the others.

For security reasons, requesting a new key prompts the store admin to validate the request before it's issued.

Treat a key like a password: anyone who has it can act on your store through the API. Keep it out of client-side code and version control, and revoke it immediately if you think it's been exposed.

How It Works

What follows is a rough shape of the API to give you a feel for it, not the full reference. Once your use case is approved, we'll walk you through the complete details, including the OpenAPI schema and working examples.

Every action is a single POST request with a JSON body, and every call is protected by your API key.

The response is always 200 OK when your request reaches an action and gets processed, even if the action itself fails for a business reason. Its body tells you which happened:

{ "ok": true, "data": { /* ... */ } }

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "..." } }

A non-200 response means the request never reached an action at all, for example a missing or invalid API key, an unknown action name, too many requests in a short window, or a malformed request body.

A few of the error codes you'll see in an ok: false body:

Code	Meaning
VALIDATION	Something in your conditions couldn't be resolved, like a metafield that doesn't exist on your store.
NOT_FOUND	The collection (or parent) you referenced doesn't exist.
CYCLE	The parent/conditions you asked for would create a loop in your hierarchy.
LIMIT_EXCEEDED	Your plan doesn't allow another collection, or another level of nesting.

What You Can Do

• Create a Managed Collection, with the same conditions and hierarchy options available in the app: nested AND/OR groups, and an optional parent so API-created collections slot into your existing tree just like ones you build by hand.
• Read a Managed Collection back, by its own ID or by the Shopify collection it maps to.
• Update a Managed Collection: change its title, conditions, or hierarchy. Fields you leave out keep their current value.
• Delete a Managed Collection.
• Ping, to confirm a key is valid before you build anything on top of it.

Here's roughly what creating a parent and a child collection looks like, chained together:

// Create the parent collection first.
const parent = await callApi("create-managed-collection", {
  title: "Summer Sale",
  filters: {
    name: "logicalGroup",
    operator: "and",
    children: [{ name: "productTag", operator: "eq", value: ["summer"] }],
  },
});

// Then create a child nested under it, using the parent's ID.
const child = await callApi("create-managed-collection", {
  title: "Summer Sale - Beachwear",
  parent: { managedCollectionId: parent.managedCollectionId },
  filters: {
    name: "logicalGroup",
    operator: "and",
    children: [{ name: "productType", operator: "eq", value: ["Beachwear"] }],
  },
});

child narrows down parent's products further, the same way nesting works anywhere else in the app. callApi here is a small wrapper you write yourself: it sends the request with your API key, and returns data on success or throws using the error above otherwise.

Use Cases

A few genuine ways stores have put the API to use:

• Syncing from an ERP or PIM. If your product categories live in another system, that system can stay the source of truth: whenever it adds, renames, or reorganizes a category, it calls the API to create or update the matching Managed Collection, nesting included. Your team keeps managing the taxonomy where they already do, and the storefront hierarchy follows automatically, instead of someone re-entering the same structure by hand in Shopify.
• Migrating from another platform. Rebuilding a large, deeply nested category tree one collection at a time in the UI is slow and error-prone. A one-time script can walk your old platform's categories and recreate the whole structure through the API in a single pass, parent/child relationships and conditions included.
• Keeping franchise or multi-store catalogs consistent. If you manage collection structure for several Shopify stores, like a franchisor rolling the same taxonomy out to every franchisee, the API lets you push a structural change from one place instead of repeating it manually in each store.
• Pulling your hierarchy into your own tools. The API isn't only for writing. An internal dashboard, reporting tool, or customer service app can read a product's collections and where they sit in the tree directly from the API, so that information is available wherever your team works, not just in the Shopify admin.

Need Something Different?

info

This API currently covers Managed Collections themselves. If you need it to do more, get in touch with our team, we'd love to hear what you're trying to build.

FAQ

How long does it take to get API access approved?

We usually reply the same business day you reach out. If your use case is a good fit, approval and setup can happen that same day too.

Is there a cost to use the API?

Not on top of your subscription. For now, the API is available to stores on the Advanced and Enterprise plans, at no extra cost.

Is there a rate limit?

Yes, but it's generous. It's there to prevent abuse, not to get in the way of normal use. If you hit it, you'll see a RATE_LIMITED response, back off and retry shortly after.

Do collections created through the API behave differently from ones I create in the app?

No, exactly the same. They're built on the same conditions and hierarchy engine as collections you create by hand, and they sync the same way.

Can I try the API on a sandbox or staging store first?

Yes, and we actually encourage it. If you have a development or staging store, get your integration working there first, then point it at your live store once you're confident in it.