Promotions

5 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.

Sale campaigns with results

GET/v1/store/promotions

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

marketing:readlistPromotions

Parameters

tab"all" | "running" | "scheduled" | "ended" | "draft"query

Response ListPromotionsResponse

itemsPromotion[]required
countsPromotionCountsrequired

Example

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

const res = await fetch('https://api.shopfa.st/v1/store/promotions', {
  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/promotions",
    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/promotions", 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

tab

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

Schedule a sale

POST/v1/store/promotions

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

marketing:writecreatePromotion

Body

namestringrequired
percentOffBpsintegerrequired
target"all" | "collections" | "products" | "categories"required
collectionIdscol_…[]required
categoryIdspcat_…[]
productIdsprd_…[]required
startsAtstringrequired
endsAtstringrequired
stacking"stack" | "exclusive"required
bannerobjectrequired
- enabledboolean
- textstring
- tone"accent" | "ink" | "canvas"
- countdownboolean
- linkstring
enabledbooleanrequired

Response Promotion

namestringrequired
percentOffBpsintegerrequired
targetPromotionTargetrequired
collectionIdsCollectionId[]required
categoryIdsCategoryId[]required
productIdsProductId[]required
startsAtTimestamprequired
endsAtTimestamprequired
stackingPromotionStackingrequired
bannerPromotionBannerrequired

10 more fields

enabledbooleanrequired
idPromotionIdrequired
statePromotionStaterequired
productCountintegerrequired
ordersintegerrequired
revenueMinorMinorUnitsrequired
savingsMinorMinorUnitsrequired
currencyCurrencyCoderequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X POST "https://api.shopfa.st/v1/store/promotions" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "percentOffBps": 100,
  "target": "all",
  "collectionIds": [
    "col_0123456789abcdefghjk"
  ],
  "categoryIds": [],
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "startsAt": "2026-10-21T12:00:00.000Z",
  "endsAt": "2026-10-21T12:00:00.000Z",
  "stacking": "stack",
  "banner": {},
  "enabled": false
}'

const res = await fetch('https://api.shopfa.st/v1/store/promotions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "string",
    "percentOffBps": 100,
    "target": "all",
    "collectionIds": [
      "col_0123456789abcdefghjk"
    ],
    "categoryIds": [],
    "productIds": [
      "prd_0123456789abcdefghjk"
    ],
    "startsAt": "2026-10-21T12:00:00.000Z",
    "endsAt": "2026-10-21T12:00:00.000Z",
    "stacking": "stack",
    "banner": {},
    "enabled": false
  }),
});
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/promotions",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "name": "string",
      "percentOffBps": 100,
      "target": "all",
      "collectionIds": [
        "col_0123456789abcdefghjk"
      ],
      "categoryIds": [],
      "productIds": [
        "prd_0123456789abcdefghjk"
      ],
      "startsAt": "2026-10-21T12:00:00.000Z",
      "endsAt": "2026-10-21T12:00:00.000Z",
      "stacking": "stack",
      "banner": {},
      "enabled": False
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/promotions", strings.NewReader(`{
  "name": "string",
  "percentOffBps": 100,
  "target": "all",
  "collectionIds": [
    "col_0123456789abcdefghjk"
  ],
  "categoryIds": [],
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "startsAt": "2026-10-21T12:00:00.000Z",
  "endsAt": "2026-10-21T12:00:00.000Z",
  "stacking": "stack",
  "banner": {},
  "enabled": false
}`))
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.

Change a sale

PUT/v1/store/promotions/{promotionId}

Or name the store: PUT /v1/stores/{storeId}/promotions/{promotionId}

marketing:writeupdatePromotion

Parameters

promotionIdprm_…pathrequired

Body

namestringrequired
percentOffBpsintegerrequired
target"all" | "collections" | "products" | "categories"required
collectionIdscol_…[]required
categoryIdspcat_…[]
productIdsprd_…[]required
startsAtstringrequired
endsAtstringrequired
stacking"stack" | "exclusive"required
bannerobjectrequired
- enabledboolean
- textstring
- tone"accent" | "ink" | "canvas"
- countdownboolean
- linkstring
enabledbooleanrequired

Response Promotion

namestringrequired
percentOffBpsintegerrequired
targetPromotionTargetrequired
collectionIdsCollectionId[]required
categoryIdsCategoryId[]required
productIdsProductId[]required
startsAtTimestamprequired
endsAtTimestamprequired
stackingPromotionStackingrequired
bannerPromotionBannerrequired

10 more fields

enabledbooleanrequired
idPromotionIdrequired
statePromotionStaterequired
productCountintegerrequired
ordersintegerrequired
revenueMinorMinorUnitsrequired
savingsMinorMinorUnitsrequired
currencyCurrencyCoderequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X PUT "https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "percentOffBps": 100,
  "target": "all",
  "collectionIds": [
    "col_0123456789abcdefghjk"
  ],
  "categoryIds": [],
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "startsAt": "2026-10-21T12:00:00.000Z",
  "endsAt": "2026-10-21T12:00:00.000Z",
  "stacking": "stack",
  "banner": {},
  "enabled": false
}'

const res = await fetch('https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "string",
    "percentOffBps": 100,
    "target": "all",
    "collectionIds": [
      "col_0123456789abcdefghjk"
    ],
    "categoryIds": [],
    "productIds": [
      "prd_0123456789abcdefghjk"
    ],
    "startsAt": "2026-10-21T12:00:00.000Z",
    "endsAt": "2026-10-21T12:00:00.000Z",
    "stacking": "stack",
    "banner": {},
    "enabled": false
  }),
});
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/promotions/prm_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "name": "string",
      "percentOffBps": 100,
      "target": "all",
      "collectionIds": [
        "col_0123456789abcdefghjk"
      ],
      "categoryIds": [],
      "productIds": [
        "prd_0123456789abcdefghjk"
      ],
      "startsAt": "2026-10-21T12:00:00.000Z",
      "endsAt": "2026-10-21T12:00:00.000Z",
      "stacking": "stack",
      "banner": {},
      "enabled": False
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PUT", "https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk", strings.NewReader(`{
  "name": "string",
  "percentOffBps": 100,
  "target": "all",
  "collectionIds": [
    "col_0123456789abcdefghjk"
  ],
  "categoryIds": [],
  "productIds": [
    "prd_0123456789abcdefghjk"
  ],
  "startsAt": "2026-10-21T12:00:00.000Z",
  "endsAt": "2026-10-21T12:00:00.000Z",
  "stacking": "stack",
  "banner": {},
  "enabled": false
}`))
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

promotionId

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 draft or scheduled sale

DELETE/v1/store/promotions/{promotionId}

Or name the store: DELETE /v1/stores/{storeId}/promotions/{promotionId}

marketing:writedeletePromotion

Parameters

promotionIdprm_…pathrequired

Response Ok

okbooleanrequired

Example

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

const res = await fetch('https://api.shopfa.st/v1/store/promotions/prm_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/promotions/prm_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/promotions/prm_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

promotionId

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

End a running sale now

POST/v1/store/promotions/{promotionId}/end

Or name the store: POST /v1/stores/{storeId}/promotions/{promotionId}/end

marketing:writeendPromotion

Parameters

promotionIdprm_…pathrequired

Response Promotion

namestringrequired
percentOffBpsintegerrequired
targetPromotionTargetrequired
collectionIdsCollectionId[]required
categoryIdsCategoryId[]required
productIdsProductId[]required
startsAtTimestamprequired
endsAtTimestamprequired
stackingPromotionStackingrequired
bannerPromotionBannerrequired

10 more fields

enabledbooleanrequired
idPromotionIdrequired
statePromotionStaterequired
productCountintegerrequired
ordersintegerrequired
revenueMinorMinorUnitsrequired
savingsMinorMinorUnitsrequired
currencyCurrencyCoderequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X POST "https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk/end" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk/end', {
  method: 'POST',
  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(
    "POST",
    "https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk/end",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/promotions/prm_0123456789abcdefghjk/end", 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

promotionId

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