Connector (API Access)

The Connector gives you programmatic access to Dynasort through a REST-style API. You can use it to connect AI assistants like Claude or ChatGPT, build custom integrations, or automate merchandising workflows — all without touching the Dynasort dashboard.

Plan requirement

The Connector is available on Pro and Enterprise plans. If you’re on a free or Basic plan, you can view the Connector page in the app, but API key generation is disabled until you upgrade.

Getting started

Open Connector from the left sidebar in the Dynasort app.

The page has three sections: API Key management, a System Prompt for AI assistants, and an API Reference card.

Generate an API key

Click Generate API Key to create a new key. The full key is displayed exactly once — copy it immediately and store it somewhere safe. Dynasort only stores a hash of the key, so it cannot be retrieved later.

Your key starts with dyn_sk_ followed by a long hex string. Only one active key is allowed at a time. If you need a new one, revoke the current key first, then generate a fresh one.

Store your key securely

Treat your API key like a password. Anyone with the key can read and modify your collections, products, and recipes through the API. If you suspect a key has been compromised, revoke it immediately from the Connector page.

Using with AI assistants

The fastest way to use the Connector is to paste the System Prompt into an AI assistant. The prompt contains your store URL, the API endpoint, authentication instructions, and a complete reference for every available action — everything the assistant needs to manage your Dynasort setup through conversation.

To set up an AI assistant:

1. Click Copy Prompt on the Connector page.
2. Open your AI assistant (Claude, ChatGPT, or similar).
3. Paste the prompt as a system message or at the start of a new conversation.
4. When the assistant asks for your API key, provide the dyn_sk_... key you generated earlier.

From there, you can ask the assistant to do things like “list my collections,” “enable sorting on the Summer Sale collection,” or “boost product X by 50 points” — and it will make the API calls for you.

One prompt, many sessions

You only need to copy the prompt once and can reuse it across conversations. The prompt is tied to your store, not to a specific session. Just provide your API key at the start of each new conversation.

Using the API directly

If you’re building a custom integration, you can call the API directly.

Endpoint: https://dynasort.immersiveecommerce.com/api/v1/

All requests are POST with a JSON body. Authenticate with a Bearer token:

curl -X POST https://dynasort.immersiveecommerce.com/api/v1/ \
  -H "Authorization: Bearer dyn_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action": "list_collections"}'

Rate limits

The API allows 60 requests per minute per store. Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per minute (60)
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

If you exceed the limit, the API returns HTTP 429 with a Retry-After header.

Response format

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "error": true,
  "message": "Human-readable description",
  "code": "error_code"
}

Error code	Meaning
unauthorized	Invalid or missing API key
rate_limited	Too many requests — retry after the reset time
permission_denied	Store plan does not include API access
invalid_action	Unknown action name
invalid_params	Missing or invalid required parameters
not_found	Requested resource not found
server_error	Internal error

Available actions

The API exposes 16 actions organized into three categories.

Collection management

Action	Description
list_collections	List all collections with their sorting status, recipe assignment, and product count
get_collection	Get detailed info about a single collection including its products
enable_collection	Enable Dynasort sorting on a collection
disable_collection	Disable sorting on a collection (reverts to configured sort order if set)
update_collection	Assign a recipe and/or set the revert sort order for a collection
bulk_toggle_collections	Enable or disable multiple collections at once
bulk_assign_recipe	Assign a recipe to multiple collections at once
sort_collection	Trigger an immediate sort using the assigned recipe
revert_collection	Revert a collection to its configured revert sort order

Recipe management

Action	Description
list_recipes	List all sorting recipes configured for your store

Product management

Action	Description
list_products	List products with their Dynasort data, boost values, and option sorting status
get_product	Get detailed info about a single product including its options
set_product_boost	Set a boost value on a product (positive = boost up, negative = push down)
enable_product	Enable option sorting on a product and configure sort rules for each option
disable_product	Disable option sorting on a product
sort_product	Trigger an immediate re-sort of a product’s options

Action reference

Every action is sent as a JSON body with an "action" field. Below are the parameters for each.

list_collections

{ "action": "list_collections" }

No required parameters. Returns an array of collections with ID, title, enabled status, current recipe, product count, and last sort time.

get_collection

{ "action": "get_collection", "collection_id": 123456789 }

Parameter	Required	Description
collection_id	Yes	Shopify collection ID

enable_collection / disable_collection

{ "action": "enable_collection", "collection_id": 123456789 }

Parameter	Required	Description
collection_id	Yes	Shopify collection ID

update_collection

{
  "action": "update_collection",
  "collection_id": 123456789,
  "metrics_id": 1,
  "revert_sorting": "best-selling"
}

Parameter	Required	Description
collection_id	Yes	Shopify collection ID
metrics_id	Yes	Recipe ID to assign (use list_recipes to find IDs)
revert_sorting	No	Sort order to revert to when disabled. Options: manual, best-selling, alpha-asc, alpha-desc, price-asc, price-desc, created-desc, created-asc

bulk_toggle_collections

{
  "action": "bulk_toggle_collections",
  "collection_ids": [123456789, 987654321],
  "status": 1
}

Parameter	Required	Description
collection_ids	Yes	Array of Shopify collection IDs
status	Yes	1 to enable, 0 to disable

bulk_assign_recipe

{
  "action": "bulk_assign_recipe",
  "collection_ids": [123456789, 987654321],
  "metrics_id": 1,
  "revert_sorting": "best-selling"
}

Parameter	Required	Description
collection_ids	Yes	Array of Shopify collection IDs
metrics_id	Yes	Recipe ID to assign
revert_sorting	No	Revert sort order

sort_collection

{ "action": "sort_collection", "collection_id": 123456789 }

Triggers an immediate sort. The collection must be enabled with a recipe assigned.

revert_collection

{ "action": "revert_collection", "collection_id": 123456789 }

Reverts the collection to its configured revert sort order.

list_recipes

{ "action": "list_recipes" }

Returns all recipes with their ID, name, attribute weights, and the number of collections using them.

list_products

{ "action": "list_products" }

Returns products with boost values, enabled status, options, and current sort settings.

get_product

{ "action": "get_product", "product_id": 123456789 }

Returns detailed info about a single product including all its options and their sorting configuration.

set_product_boost

{
  "action": "set_product_boost",
  "product_id": 123456789,
  "boost": 50
}

Parameter	Required	Description
product_id	Yes	Shopify product ID
boost	Yes	Integer added to the product’s ranking score. Positive = boost up, negative = push down, 0 = no boost

enable_product

Enables option sorting on a product. Option sorting reorders the variant options (like Color or Size) within a single product based on performance data.

{
  "action": "enable_product",
  "product_id": 123456789,
  "options": [
    {
      "option_id": 111,
      "option_name": "Color",
      "sort_type": "sales",
      "sold_out": "bottom",
      "direction": "desc",
      "days": "30"
    }
  ]
}

Parameter	Required	Description
product_id	Yes	Shopify product ID
options	No	Array of option sorting configurations (see below)

Option configuration fields:

Field	Required	Description
option_id	Yes	The option ID from the product (use get_product to find these)
option_name	Yes	The option name (e.g. “Color”, “Size”)
sort_type	Yes	Sort method — see table below
sold_out	No	Where to place sold-out variants: bottom (default), top, or ignore
direction	No	Sort direction: desc (default) or asc
days	No	Time window for sales/revenue sorts: 7, 30 (default), 60, 90, 365, or all
csv_pattern	No	Custom order for comma_separated sort type (e.g. "Red,Blue,Green")
common_size	No	Size system for common_sizes sort type (e.g. "us_apparel", "us_shoes")

Available sort types:

Sort type	What it sorts by
off	No sorting for this option
alphabetical	Alphabetical order
sales	Units sold (within the time window)
revenues	Revenue generated
prices	Variant price
compare_at_prices	Compare-at price
costs	Cost per item
inventories	Available inventory
margins	Profit margin
discount_amounts	Discount amount
discount_percentages	Discount percentage
numeric	Numeric value in the option name
variant_ages	How recently the variant was added
variants_in_stock	In-stock status
comma_separated	Custom order defined by csv_pattern
common_sizes	Standard size ordering (S, M, L, XL, etc.)

disable_product

{ "action": "disable_product", "product_id": 123456789 }

Disables option sorting on the product.

sort_product

{ "action": "sort_product", "product_id": 123456789 }

Triggers an immediate re-sort of the product’s options using its saved configuration. The product must be enabled with option sorting configured.

Sort after enabling

After enabling a product with option sorting, call sort_product to apply the sort immediately. Otherwise, the sort will happen on the next scheduled cron run.

Managing API keys

• One active key at a time. If you need to rotate your key, revoke the current one first, then generate a new one.
• Revoking a key is immediate. Any requests using the old key will fail with a 401 unauthorized error as soon as the key is revoked.
• Keys don’t expire. An active key stays valid until you revoke it manually.
• Key history is preserved. Revoked keys remain visible in the Connector page with a “Revoked” badge so you have an audit trail.