Offers

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.

Add-on and upsell rules with 30-day conversions

GET/v1/store/offers

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

catalog:readlistOfferRules

Response ListOfferRulesResponse

rulesOfferRule[]required

Example

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

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

When product X is in the cart, offer Y at Z

POST/v1/store/offers

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

catalog:writecreateOfferRule

Body

namestringrequired
kind"order_bump" | "upsell" | "cross_sell"required
triggerProductIdsprd_…[]required
offerProductIdprd_…required
offerVariantIdvar_… | nullrequired
discountobjectrequired
headlinestringrequired
bodystringrequired
placement"cart" | "checkout" | "product_page"required
enabledbooleanrequired

Response OfferRule

idOfferRuleIdrequired
namestringrequired
kindOfferKindrequired
triggerProductIdsProductId[]required
offerProductIdProductIdrequired
offerVariantIdVariantId | nullrequired
discountOfferDiscountrequired
headlinestringrequired
bodystringrequired
placementOfferPlacementrequired

8 more fields

enabledbooleanrequired
positionintegerrequired
regularPriceMinorMinorUnitsrequired
offerPriceMinorMinorUnitsrequired
currencyCurrencyCoderequired
conversions30dintegerrequired
revenue30dMinorMinorUnitsrequired
updatedAtTimestamprequired

Example

curl -X POST "https://api.shopfa.st/v1/store/offers" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "kind": "order_bump",
  "triggerProductIds": [
    "prd_0123456789abcdefghjk"
  ],
  "offerProductId": "prd_0123456789abcdefghjk",
  "offerVariantId": "var_0123456789abcdefghjk",
  "discount": {
    "kind": "none"
  },
  "headline": "string",
  "body": "string",
  "placement": "cart",
  "enabled": false
}'

const res = await fetch('https://api.shopfa.st/v1/store/offers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "string",
    "kind": "order_bump",
    "triggerProductIds": [
      "prd_0123456789abcdefghjk"
    ],
    "offerProductId": "prd_0123456789abcdefghjk",
    "offerVariantId": "var_0123456789abcdefghjk",
    "discount": {
      "kind": "none"
    },
    "headline": "string",
    "body": "string",
    "placement": "cart",
    "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/offers",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "name": "string",
      "kind": "order_bump",
      "triggerProductIds": [
        "prd_0123456789abcdefghjk"
      ],
      "offerProductId": "prd_0123456789abcdefghjk",
      "offerVariantId": "var_0123456789abcdefghjk",
      "discount": {
        "kind": "none"
      },
      "headline": "string",
      "body": "string",
      "placement": "cart",
      "enabled": False
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/offers", strings.NewReader(`{
  "name": "string",
  "kind": "order_bump",
  "triggerProductIds": [
    "prd_0123456789abcdefghjk"
  ],
  "offerProductId": "prd_0123456789abcdefghjk",
  "offerVariantId": "var_0123456789abcdefghjk",
  "discount": {
    "kind": "none"
  },
  "headline": "string",
  "body": "string",
  "placement": "cart",
  "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.

Update an offer rule

PUT/v1/store/offers/{ruleId}

Or name the store: PUT /v1/stores/{storeId}/offers/{ruleId}

catalog:writeupdateOfferRule

Parameters

ruleIdoffr_…pathrequired

Body

namestringrequired
kind"order_bump" | "upsell" | "cross_sell"required
triggerProductIdsprd_…[]required
offerProductIdprd_…required
offerVariantIdvar_… | nullrequired
discountobjectrequired
headlinestringrequired
bodystringrequired
placement"cart" | "checkout" | "product_page"required
enabledbooleanrequired

Response OfferRule

idOfferRuleIdrequired
namestringrequired
kindOfferKindrequired
triggerProductIdsProductId[]required
offerProductIdProductIdrequired
offerVariantIdVariantId | nullrequired
discountOfferDiscountrequired
headlinestringrequired
bodystringrequired
placementOfferPlacementrequired

8 more fields

enabledbooleanrequired
positionintegerrequired
regularPriceMinorMinorUnitsrequired
offerPriceMinorMinorUnitsrequired
currencyCurrencyCoderequired
conversions30dintegerrequired
revenue30dMinorMinorUnitsrequired
updatedAtTimestamprequired

Example

curl -X PUT "https://api.shopfa.st/v1/store/offers/offr_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "kind": "order_bump",
  "triggerProductIds": [
    "prd_0123456789abcdefghjk"
  ],
  "offerProductId": "prd_0123456789abcdefghjk",
  "offerVariantId": "var_0123456789abcdefghjk",
  "discount": {
    "kind": "none"
  },
  "headline": "string",
  "body": "string",
  "placement": "cart",
  "enabled": false
}'

const res = await fetch('https://api.shopfa.st/v1/store/offers/offr_0123456789abcdefghjk', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "string",
    "kind": "order_bump",
    "triggerProductIds": [
      "prd_0123456789abcdefghjk"
    ],
    "offerProductId": "prd_0123456789abcdefghjk",
    "offerVariantId": "var_0123456789abcdefghjk",
    "discount": {
      "kind": "none"
    },
    "headline": "string",
    "body": "string",
    "placement": "cart",
    "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/offers/offr_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "name": "string",
      "kind": "order_bump",
      "triggerProductIds": [
        "prd_0123456789abcdefghjk"
      ],
      "offerProductId": "prd_0123456789abcdefghjk",
      "offerVariantId": "var_0123456789abcdefghjk",
      "discount": {
        "kind": "none"
      },
      "headline": "string",
      "body": "string",
      "placement": "cart",
      "enabled": False
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PUT", "https://api.shopfa.st/v1/store/offers/offr_0123456789abcdefghjk", strings.NewReader(`{
  "name": "string",
  "kind": "order_bump",
  "triggerProductIds": [
    "prd_0123456789abcdefghjk"
  ],
  "offerProductId": "prd_0123456789abcdefghjk",
  "offerVariantId": "var_0123456789abcdefghjk",
  "discount": {
    "kind": "none"
  },
  "headline": "string",
  "body": "string",
  "placement": "cart",
  "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

ruleId

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 an offer rule

DELETE/v1/store/offers/{ruleId}

Or name the store: DELETE /v1/stores/{storeId}/offers/{ruleId}

catalog:writedeleteOfferRule

Parameters

ruleIdoffr_…pathrequired

Response Ok

okbooleanrequired

Example

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

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

ruleId

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 which offer shows first when several match

POST/v1/store/offers/reorder

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

catalog:writereorderOfferRules

Body

idsoffr_…[]required

Response ReorderOfferRulesResponse

rulesOfferRule[]required

Example

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

const res = await fetch('https://api.shopfa.st/v1/store/offers/reorder', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ids": [
      "offr_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/offers/reorder",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "ids": [
        "offr_0123456789abcdefghjk"
      ]
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/offers/reorder", strings.NewReader(`{
  "ids": [
    "offr_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.