API resource

Store collections and discounts

Group products into collections and run discounts: codes buyers type, or automatic discounts applied at checkout, as a percentage, a fixed amount or free shipping. Discounts need the discounts permission (see Get a store). Pick the store with accountId.

List collections

GET/v1/commerce/collections

Works on: Shopify, WooCommerce

Lists the store's product collections. Cursor-paginated like products. List a collection's products with GET /v1/commerce/products?collectionId=....

Query parameters

accountIdstringrequired

Connected store account id.

limitinteger

cursorstring

querystring

Platform collection search syntax (Shopify: title, handle, collection_type, ...).

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/collections?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "collections": [
    {
      "id": "string",
      "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
      "platform": "shopify",
      "title": "string",
      "handle": "string",
      "descriptionHtml": "string",
      "image": {
        "id": "string",
        "url": "string",
        "altText": "string"
      },
      "sortOrder": "manual",
      "productCount": 0,
      "seo": {
        "title": "string",
        "description": "string"
      },
      "updatedAt": "2026-10-10T00:00:00.000Z",
      "platformData": {}
    }
  ],
  "nextCursor": "string"
}

Create a collection

POST/v1/commerce/collections

Works on: Shopify, WooCommerce

Creates a collection, optionally with hand-picked products. On Shopify the collection starts unpublished from the online store; publish it from the Shopify admin.

Body

accountIdstringrequired

titlestringrequired

descriptionHtmlstring

handlestring

sortOrderstring

seoobject

imageobject

productIdsstring[]

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/collections" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "title": "string"
  }'

Response 200

{
  "collection": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "handle": "string",
    "descriptionHtml": "string",
    "image": {
      "id": "string",
      "url": "string",
      "altText": "string"
    },
    "sortOrder": "manual",
    "productCount": 0,
    "seo": {
      "title": "string",
      "description": "string"
    },
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "platformData": {}
  }
}

Delete a collection

DELETE/v1/commerce/collections/{collectionId}

Works on: Shopify, WooCommerce

Deletes the collection. Its products are not affected.

Path parameters

collectionIdstringrequired

Platform-native collection id.

Query parameters

accountIdstringrequired

Connected store account id.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "deleted": true,
  "collectionId": "459876543210"
}

Get a collection

GET/v1/commerce/collections/{collectionId}

Works on: Shopify, WooCommerce

One collection (a category on WooCommerce) with its image, sort order and product count. List its products with GET /v1/commerce/products?collectionId=. Needs collections.read.

Path parameters

collectionIdstringrequired

Platform-native collection id.

Query parameters

accountIdstringrequired

Connected store account id.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "collection": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "handle": "string",
    "descriptionHtml": "string",
    "image": {
      "id": "string",
      "url": "string",
      "altText": "string"
    },
    "sortOrder": "manual",
    "productCount": 0,
    "seo": {
      "title": "string",
      "description": "string"
    },
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "platformData": {}
  }
}

Update a collection

PATCH/v1/commerce/collections/{collectionId}

Works on: Shopify, WooCommerce

Partial update; at least one field besides accountId is required. Change membership with POST /v1/commerce/collections/{collectionId}/products.

Path parameters

collectionIdstringrequired

Platform-native collection id.

Body

accountIdstringrequired

titlestring

descriptionHtmlstring

handlestring

sortOrderstring

seoobject

imageobject

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'

Response 200

{
  "collection": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "handle": "string",
    "descriptionHtml": "string",
    "image": {
      "id": "string",
      "url": "string",
      "altText": "string"
    },
    "sortOrder": "manual",
    "productCount": 0,
    "seo": {
      "title": "string",
      "description": "string"
    },
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "platformData": {}
  }
}

Publish or unpublish a collection

POST/v1/commerce/collections/{collectionId}/channels

Works on: Shopify, WooCommerce

Publishes to and/or unpublishes from sales channels (the online store, Shop, POS and others). List channels with GET /v1/commerce/channels.

Path parameters

collectionIdstringrequired

Platform-native id.

Body

accountIdstringrequired

publishstring[]

Channel ids from GET /v1/commerce/channels.

unpublishstring[]

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210/channels" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'

Response 200

{
  "collectionId": "459876543210",
  "published": [
    "string"
  ],
  "unpublished": [
    "string"
  ]
}

Delete collection metafields

DELETE/v1/commerce/collections/{collectionId}/metafields

Works on: Shopify, WooCommerce

Deletes the collection metafields named in keys (comma-separated namespace.key, up to 25). Needs collections.metafields: WooCommerce answers 400 platform_not_supported.

Path parameters

collectionIdstringrequired

Platform-native id.

Query parameters

accountIdstringrequired

Connected store account id.

keysstringrequired

Comma-separated namespace.key pairs.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210/metafields?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H&keys=%3Ckeys%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "deleted": 0
}

List collection metafields

GET/v1/commerce/collections/{collectionId}/metafields

Works on: Shopify, WooCommerce

The collection's metafields as namespace, key, type and value. Needs collections.metafields: WooCommerce keeps custom fields on products only and answers 400 platform_not_supported.

Path parameters

collectionIdstringrequired

Platform-native id.

Query parameters

accountIdstringrequired

Connected store account id.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210/metafields?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "metafields": [
    {
      "namespace": "string",
      "key": "string",
      "type": "string",
      "value": "string"
    }
  ]
}

Set collection metafields

PUT/v1/commerce/collections/{collectionId}/metafields

Works on: Shopify, WooCommerce

Creates or updates custom fields by namespace and key. Needs collections.metafields: WooCommerce keeps custom fields on products only and answers 400 platform_not_supported.

Path parameters

collectionIdstringrequired

Platform-native id.

Body

accountIdstringrequired

metafieldsobject[]required

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210/metafields" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "metafields": [
      {
        "namespace": "string",
        "key": "string",
        "type": "string",
        "value": "string"
      }
    ]
  }'

Response 200

{
  "metafields": [
    {
      "namespace": "string",
      "key": "string",
      "type": "string",
      "value": "string"
    }
  ]
}

Add or remove products in a collection

POST/v1/commerce/collections/{collectionId}/products

Works on: Shopify, WooCommerce

Adds and/or removes hand-picked products. Products a collection includes through its own rules are not affected. pending is true when the platform finishes the change in the background; the product count then catches up a few seconds later.

Path parameters

collectionIdstringrequired

Platform-native collection id.

Body

accountIdstringrequired

addstring[]

removestring[]

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210/products" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'

Response 200

{
  "collection": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "handle": "string",
    "descriptionHtml": "string",
    "image": {
      "id": "string",
      "url": "string",
      "altText": "string"
    },
    "sortOrder": "manual",
    "productCount": 0,
    "seo": {
      "title": "string",
      "description": "string"
    },
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "platformData": {}
  },
  "pending": true
}

Reorder products in a collection

POST/v1/commerce/collections/{collectionId}/reorder

Works on: Shopify, WooCommerce

Moves products to new 0-based positions. Only for collections sorted manual.

Path parameters

collectionIdstringrequired

Platform-native id.

Body

accountIdstringrequired

movesobject[]required

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/collections/459876543210/reorder" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "moves": [
      {
        "productId": "8214569812345",
        "position": 0
      }
    ]
  }'

Response 200

{
  "pending": true
}

List discounts

GET/v1/commerce/discounts

Works on: Shopify, WooCommerce

The store's discounts (Shopify code and automatic discounts, WooCommerce coupons), cursor-paginated with limit, cursor and an optional query. Each discount lists its first 10 codes; codeCount has the total. Needs discounts.read.

Query parameters

accountIdstringrequired

Connected store account id.

limitinteger

cursorstring

querystring

Platform search syntax, passed through.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "discounts": [
    {
      "id": "string",
      "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
      "platform": "shopify",
      "title": "string",
      "method": "code",
      "type": "percentage",
      "codes": [
        "string"
      ],
      "codeCount": 0,
      "value": {
        "type": "percentage",
        "percentage": 15
      },
      "appliesTo": {
        "type": "all",
        "productIds": [],
        "variantIds": [],
        "collectionIds": []
      },
      "minimum": {
        "type": "subtotal",
        "amount": {},
        "quantity": 0
      },
      "usageLimit": 0,
      "oncePerCustomer": true,
      "usageCount": 0,
      "startsAt": "2026-10-10T00:00:00.000Z",
      "endsAt": "2026-10-10T00:00:00.000Z",
      "status": "active",
      "platformStatus": "string",
      "summary": "string",
      "platformData": {}
    }
  ],
  "nextCursor": "string"
}

Create a discount

POST/v1/commerce/discounts

Works on: Shopify, WooCommerce

Creates a code discount (buyers enter a code) or an automatic one (applied at checkout), as a percentage, a fixed amount or free shipping. It applies to every product unless productIds or collectionIds narrow it, and to every buyer.

Body

accountIdstringrequired

titlestringrequired

methodstringrequired

typestringrequired

codestring

Required for method code.

percentagenumber

For type percentage, e.g. 15 for 15%.

amountstring

For type fixed_amount, a decimal in the store currency.

appliesOnEachItemboolean

fixed_amount only: take the amount off each item instead of once per order.

minimumSubtotalstring

Minimum order subtotal, a decimal in the store currency.

minimumQuantityinteger

usageLimitinteger

Code discounts only: total uses allowed.

oncePerCustomerboolean

Code discounts only.

startsAtstring

Defaults to now.

endsAtstring

productIdsstring[]

collectionIdsstring[]

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "title": "string",
    "method": "code",
    "type": "percentage"
  }'

Response 200

{
  "discount": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "method": "code",
    "type": "percentage",
    "codes": [
      "string"
    ],
    "codeCount": 0,
    "value": {
      "type": "percentage",
      "percentage": 15
    },
    "appliesTo": {
      "type": "all",
      "productIds": [
        "string"
      ],
      "variantIds": [
        "string"
      ],
      "collectionIds": [
        "string"
      ]
    },
    "minimum": {
      "type": "subtotal",
      "amount": {
        "amount": "19.90",
        "currency": "USD"
      },
      "quantity": 0
    },
    "usageLimit": 0,
    "oncePerCustomer": true,
    "usageCount": 0,
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "active",
    "platformStatus": "string",
    "summary": "string",
    "platformData": {}
  }
}

Delete a discount

DELETE/v1/commerce/discounts/{discountId}

Works on: Shopify, WooCommerce

Deletes the discount; its codes stop working at checkout. This cannot be undone. Needs discounts.write.

Path parameters

discountIdstringrequired

Platform-native id.

Query parameters

accountIdstringrequired

Connected store account id.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts/1432109876543?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "deleted": true,
  "discountId": "1432109876543"
}

Get a discount

GET/v1/commerce/discounts/{discountId}

Works on: Shopify, WooCommerce

One discount with its value, targets, minimum, usage and schedule. Needs discounts.read.

Path parameters

discountIdstringrequired

Platform-native id.

Query parameters

accountIdstringrequired

Connected store account id.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts/1432109876543?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "discount": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "method": "code",
    "type": "percentage",
    "codes": [
      "string"
    ],
    "codeCount": 0,
    "value": {
      "type": "percentage",
      "percentage": 15
    },
    "appliesTo": {
      "type": "all",
      "productIds": [
        "string"
      ],
      "variantIds": [
        "string"
      ],
      "collectionIds": [
        "string"
      ]
    },
    "minimum": {
      "type": "subtotal",
      "amount": {
        "amount": "19.90",
        "currency": "USD"
      },
      "quantity": 0
    },
    "usageLimit": 0,
    "oncePerCustomer": true,
    "usageCount": 0,
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "active",
    "platformStatus": "string",
    "summary": "string",
    "platformData": {}
  }
}

Update a discount

PATCH/v1/commerce/discounts/{discountId}

Works on: Shopify, WooCommerce

Changes a percentage, fixed-amount or free-shipping discount. Buy-X-get-Y and app discounts are read-only here.

Path parameters

discountIdstringrequired

Platform-native id.

Body

accountIdstringrequired

titlestring

codestring

Required for method code.

percentagenumber

For type percentage, e.g. 15 for 15%.

amountstring

For type fixed_amount, a decimal in the store currency.

appliesOnEachItemboolean

fixed_amount only: take the amount off each item instead of once per order.

minimumSubtotalstring

Minimum order subtotal, a decimal in the store currency.

minimumQuantityinteger

usageLimitinteger

Code discounts only: total uses allowed.

oncePerCustomerboolean

Code discounts only.

startsAtstring

Defaults to now.

endsAtstring

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts/1432109876543" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'

Response 200

{
  "discount": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "method": "code",
    "type": "percentage",
    "codes": [
      "string"
    ],
    "codeCount": 0,
    "value": {
      "type": "percentage",
      "percentage": 15
    },
    "appliesTo": {
      "type": "all",
      "productIds": [
        "string"
      ],
      "variantIds": [
        "string"
      ],
      "collectionIds": [
        "string"
      ]
    },
    "minimum": {
      "type": "subtotal",
      "amount": {
        "amount": "19.90",
        "currency": "USD"
      },
      "quantity": 0
    },
    "usageLimit": 0,
    "oncePerCustomer": true,
    "usageCount": 0,
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "active",
    "platformStatus": "string",
    "summary": "string",
    "platformData": {}
  }
}

Add codes to a discount

POST/v1/commerce/discounts/{discountId}/codes

Works on: Shopify, WooCommerce

Adds up to 250 more codes to a code discount, for example one per influencer. The platform adds them in the background. Needs discounts.codes, which WooCommerce stores do not have.

Path parameters

discountIdstringrequired

Platform-native id.

Body

accountIdstringrequired

codesstring[]required

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts/1432109876543/codes" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "codes": [
      "string"
    ]
  }'

Response 200

{
  "pending": true
}

Activate or deactivate a discount

POST/v1/commerce/discounts/{discountId}/state

Works on: Shopify, WooCommerce

Deactivating ends the discount now; activating starts it now.

Path parameters

discountIdstringrequired

Platform-native id.

Body

accountIdstringrequired

activebooleanrequired

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/discounts/1432109876543/state" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "active": true
  }'

Response 200

{
  "discount": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "title": "string",
    "method": "code",
    "type": "percentage",
    "codes": [
      "string"
    ],
    "codeCount": 0,
    "value": {
      "type": "percentage",
      "percentage": 15
    },
    "appliesTo": {
      "type": "all",
      "productIds": [
        "string"
      ],
      "variantIds": [
        "string"
      ],
      "collectionIds": [
        "string"
      ]
    },
    "minimum": {
      "type": "subtotal",
      "amount": {
        "amount": "19.90",
        "currency": "USD"
      },
      "quantity": 0
    },
    "usageLimit": 0,
    "oncePerCustomer": true,
    "usageCount": 0,
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "active",
    "platformStatus": "string",
    "summary": "string",
    "platformData": {}
  }
}

PreviousStore products and stock NextStore pages, menus and catalog sync