Collections

6 endpoints. Each needs an API key or OAuth token with the scope shown; the key already names its store, so paths start at /v1/store. Generated from the live contract; also in openapi.json.

Collections in storefront order

GET/v1/store/collections

Or name the store: GET /v1/stores/{storeId}/collections

catalog:readlistCollections

Response ListCollectionsResponse

collectionsStoreCollection[]required

Example

curl "https://api.shopfa.st/v1/store/collections" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/collections', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.shopfa.st/v1/store/collections",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("GET", "https://api.shopfa.st/v1/store/collections", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Create a collection

POST/v1/store/collections

Or name the store: POST /v1/stores/{storeId}/collections

catalog:writecreateCollection

Body

handlestringrequired
titlestringrequired
descriptionstringrequired
productIdsprd_…[]required
sort"manual" | "best_selling" | "newest" | "price_asc" | "price_desc" | "title"required
publishedbooleanrequired
kind"manual" | "automatic"
rulesobject[]
- field"type" | "tag" | "price" | "name" | "pricing_mode" | "created_days" | "category"required
- op"equals" | "not_equals" | "contains" | "greater_than" | "less_than"required
- valuestringrequired
match"all" | "any"
imageUrlstring | null
seoTitlestring | null
seoDescriptionstring | null
templateSuffixstring | null

Response StoreCollection

idCollectionIdrequired
handlePageHandlerequired
titlestringrequired
descriptionstringrequired
productIdsProductId[]required
sortCollectionSortrequired
publishedbooleanrequired
updatedAtTimestamprequired
kind"manual" | "automatic"required
rulesCollectionRule[]required

7 more fields

match"all" | "any"required
imageUrlstring | nullrequired
seoTitlestring | nullrequired
seoDescriptionstring | nullrequired
positionintegerrequired
matchedProductIdsProductId[]required
templateSuffixstring | nullrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/collections" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "string",
  "title": "string",
  "description": "string",
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "sort": "manual",
  "published": false,
  "kind": "manual",
  "rules": [],
  "match": "all",
  "imageUrl": null,
  "seoTitle": null,
  "seoDescription": null,
  "templateSuffix": "string"
}'

const res = await fetch('https://api.shopfa.st/v1/store/collections', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "handle": "string",
    "title": "string",
    "description": "string",
    "productIds": [
      "prd_0123456789abcdefghjk"
    ],
    "sort": "manual",
    "published": false,
    "kind": "manual",
    "rules": [],
    "match": "all",
    "imageUrl": null,
    "seoTitle": null,
    "seoDescription": null,
    "templateSuffix": "string"
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.shopfa.st/v1/store/collections",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "handle": "string",
      "title": "string",
      "description": "string",
      "productIds": [
        "prd_0123456789abcdefghjk"
      ],
      "sort": "manual",
      "published": False,
      "kind": "manual",
      "rules": [],
      "match": "all",
      "imageUrl": None,
      "seoTitle": None,
      "seoDescription": None,
      "templateSuffix": "string"
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/collections", strings.NewReader(`{
  "handle": "string",
  "title": "string",
  "description": "string",
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "sort": "manual",
  "published": false,
  "kind": "manual",
  "rules": [],
  "match": "all",
  "imageUrl": null,
  "seoTitle": null,
  "seoDescription": null,
  "templateSuffix": "string"
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Update a collection

PUT/v1/store/collections/{collectionId}

Or name the store: PUT /v1/stores/{storeId}/collections/{collectionId}

catalog:writeupdateCollection

Parameters

collectionIdcol_…pathrequired

Body

handlestringrequired
titlestringrequired
descriptionstringrequired
productIdsprd_…[]required
sort"manual" | "best_selling" | "newest" | "price_asc" | "price_desc" | "title"required
publishedbooleanrequired
kind"manual" | "automatic"
rulesobject[]
- field"type" | "tag" | "price" | "name" | "pricing_mode" | "created_days" | "category"required
- op"equals" | "not_equals" | "contains" | "greater_than" | "less_than"required
- valuestringrequired
match"all" | "any"
imageUrlstring | null
seoTitlestring | null
seoDescriptionstring | null
templateSuffixstring | null

Response StoreCollection

idCollectionIdrequired
handlePageHandlerequired
titlestringrequired
descriptionstringrequired
productIdsProductId[]required
sortCollectionSortrequired
publishedbooleanrequired
updatedAtTimestamprequired
kind"manual" | "automatic"required
rulesCollectionRule[]required

7 more fields

match"all" | "any"required
imageUrlstring | nullrequired
seoTitlestring | nullrequired
seoDescriptionstring | nullrequired
positionintegerrequired
matchedProductIdsProductId[]required
templateSuffixstring | nullrequired

Example

curl -X PUT "https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "string",
  "title": "string",
  "description": "string",
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "sort": "manual",
  "published": false,
  "kind": "manual",
  "rules": [],
  "match": "all",
  "imageUrl": null,
  "seoTitle": null,
  "seoDescription": null,
  "templateSuffix": "string"
}'

const res = await fetch('https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "handle": "string",
    "title": "string",
    "description": "string",
    "productIds": [
      "prd_0123456789abcdefghjk"
    ],
    "sort": "manual",
    "published": false,
    "kind": "manual",
    "rules": [],
    "match": "all",
    "imageUrl": null,
    "seoTitle": null,
    "seoDescription": null,
    "templateSuffix": "string"
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "PUT",
    "https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "handle": "string",
      "title": "string",
      "description": "string",
      "productIds": [
        "prd_0123456789abcdefghjk"
      ],
      "sort": "manual",
      "published": False,
      "kind": "manual",
      "rules": [],
      "match": "all",
      "imageUrl": None,
      "seoTitle": None,
      "seoDescription": None,
      "templateSuffix": "string"
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PUT", "https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk", strings.NewReader(`{
  "handle": "string",
  "title": "string",
  "description": "string",
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "sort": "manual",
  "published": false,
  "kind": "manual",
  "rules": [],
  "match": "all",
  "imageUrl": null,
  "seoTitle": null,
  "seoDescription": null,
  "templateSuffix": "string"
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

collectionId

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Delete a collection

DELETE/v1/store/collections/{collectionId}

Or name the store: DELETE /v1/stores/{storeId}/collections/{collectionId}

catalog:writedeleteCollection

Parameters

collectionIdcol_…pathrequired

Response Ok

okbooleanrequired

Example

curl -X DELETE "https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "DELETE",
    "https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("DELETE", "https://api.shopfa.st/v1/store/collections/col_0123456789abcdefghjk", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

collectionId

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Set the storefront order of collections

POST/v1/store/collections/reorder

Or name the store: POST /v1/stores/{storeId}/collections/reorder

catalog:writereorderCollections

Body

idscol_…[]required

Response ReorderCollectionsResponse

collectionsStoreCollection[]required

Example

curl -X POST "https://api.shopfa.st/v1/store/collections/reorder" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "col_0123456789abcdefghjk"
  ]
}'

const res = await fetch('https://api.shopfa.st/v1/store/collections/reorder', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ids": [
      "col_0123456789abcdefghjk"
    ]
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.shopfa.st/v1/store/collections/reorder",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "ids": [
        "col_0123456789abcdefghjk"
      ]
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/collections/reorder", strings.NewReader(`{
  "ids": [
    "col_0123456789abcdefghjk"
  ]
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Products an automatic collection would contain

POST/v1/store/collections/preview

Or name the store: POST /v1/stores/{storeId}/collections/preview

catalog:writepreviewCollectionRules

Body

rulesobject[]required
- field"type" | "tag" | "price" | "name" | "pricing_mode" | "created_days" | "category"required
- op"equals" | "not_equals" | "contains" | "greater_than" | "less_than"required
- valuestringrequired
match"all" | "any"required

Response PreviewCollectionRulesResponse

productIdsProductId[]required

Example

curl -X POST "https://api.shopfa.st/v1/store/collections/preview" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "field": "type",
      "op": "equals",
      "value": "string"
    }
  ],
  "match": "all"
}'

const res = await fetch('https://api.shopfa.st/v1/store/collections/preview', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "rules": [
      {
        "field": "type",
        "op": "equals",
        "value": "string"
      }
    ],
    "match": "all"
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.shopfa.st/v1/store/collections/preview",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "rules": [
        {
          "field": "type",
          "op": "equals",
          "value": "string"
        }
      ],
      "match": "all"
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/collections/preview", strings.NewReader(`{
  "rules": [
    {
      "field": "type",
      "op": "equals",
      "value": "string"
    }
  ],
  "match": "all"
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.