Affiliates

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.

Affiliates with clicks, conversions and what you owe

GET/v1/store/affiliates

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

marketing:readlistAffiliates

Parameters

tab"all" | "active" | "pending" | "paused"query
qstring | nullquery
cursorstring | nullquery
limitinteger | stringquery
sort"affiliate" | "code" | "rate" | "clicks" | "orders" | "conversion" | "revenue" | "owed" | "paid" | "status" | "created"query
dir"asc" | "desc"query

Response ListAffiliatesResponse

itemsAffiliateRow[]required
nextCursorCursor | nullrequired
countsAffiliateCountsrequired

Example

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

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

tabqcursorlimitsortdir

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

Add an affiliate (emailed their link)

POST/v1/store/affiliates

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

marketing:writecreateAffiliate

Body

namestringrequired
emailstringrequired
codestring | nullrequired
commissionBpsinteger | nullrequired
payoutEmailstring | null
newCustomersOnlyboolean
reward"cash" | "store_credit" | null

Response AffiliateDetail

idAffiliateIdrequired
namestringrequired
emailEmailrequired
codestringrequired
statusAffiliateStatusrequired
commissionBpsBps | nullrequired
effectiveBpsBpsrequired
newCustomersOnlybooleanrequired
effectiveNewCustomersOnlybooleanrequired
rewardAffiliateReward | nullrequired

17 more fields

effectiveRewardAffiliateRewardrequired
clicksintegerrequired
conversionsintegerrequired
conversionBpsBpsrequired
revenueMinorMinorUnitsrequired
pendingMinorMinorUnitsrequired
owedMinorMinorUnitsrequired
paidMinorMinorUnitsrequired
storeCreditMinorMinorUnitsrequired
currencyCurrencyCoderequired
linkstringrequired
createdAtTimestamprequired
payoutEmailstringrequired
notestringrequired
commissionsAffiliateCommission[]required
payoutsAffiliatePayout[]required
dailyobject[]required
- dateIsoDaterequired
- clicksintegerrequired
- conversionsintegerrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/affiliates" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "email": "[email protected]",
  "code": "string",
  "commissionBps": 0,
  "payoutEmail": null,
  "newCustomersOnly": null,
  "reward": null
}'

const res = await fetch('https://api.shopfa.st/v1/store/affiliates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "string",
    "email": "[email protected]",
    "code": "string",
    "commissionBps": 0,
    "payoutEmail": null,
    "newCustomersOnly": null,
    "reward": null
  }),
});
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/affiliates",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "name": "string",
      "email": "[email protected]",
      "code": "string",
      "commissionBps": 0,
      "payoutEmail": None,
      "newCustomersOnly": None,
      "reward": None
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/affiliates", strings.NewReader(`{
  "name": "string",
  "email": "[email protected]",
  "code": "string",
  "commissionBps": 0,
  "payoutEmail": null,
  "newCustomersOnly": null,
  "reward": null
}`))
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.

One affiliate with commissions and payouts

GET/v1/store/affiliates/{affiliateId}

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

marketing:readgetAffiliate

Parameters

affiliateIdaff_…pathrequired

Response AffiliateDetail

idAffiliateIdrequired
namestringrequired
emailEmailrequired
codestringrequired
statusAffiliateStatusrequired
commissionBpsBps | nullrequired
effectiveBpsBpsrequired
newCustomersOnlybooleanrequired
effectiveNewCustomersOnlybooleanrequired
rewardAffiliateReward | nullrequired

17 more fields

effectiveRewardAffiliateRewardrequired
clicksintegerrequired
conversionsintegerrequired
conversionBpsBpsrequired
revenueMinorMinorUnitsrequired
pendingMinorMinorUnitsrequired
owedMinorMinorUnitsrequired
paidMinorMinorUnitsrequired
storeCreditMinorMinorUnitsrequired
currencyCurrencyCoderequired
linkstringrequired
createdAtTimestamprequired
payoutEmailstringrequired
notestringrequired
commissionsAffiliateCommission[]required
payoutsAffiliatePayout[]required
dailyobject[]required
- dateIsoDaterequired
- clicksintegerrequired
- conversionsintegerrequired

Example

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

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

affiliateId

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

Approve, pause or change an affiliate

PATCH/v1/store/affiliates/{affiliateId}

Or name the store: PATCH /v1/stores/{storeId}/affiliates/{affiliateId}

marketing:writeupdateAffiliate

Parameters

affiliateIdaff_…pathrequired

Body

status"pending" | "active" | "paused" | "rejected"
commissionBpsinteger | null
notestring
payoutEmailstring | null
namestring
newCustomersOnlyboolean
reward"cash" | "store_credit" | null

Response AffiliateDetail

idAffiliateIdrequired
namestringrequired
emailEmailrequired
codestringrequired
statusAffiliateStatusrequired
commissionBpsBps | nullrequired
effectiveBpsBpsrequired
newCustomersOnlybooleanrequired
effectiveNewCustomersOnlybooleanrequired
rewardAffiliateReward | nullrequired

17 more fields

effectiveRewardAffiliateRewardrequired
clicksintegerrequired
conversionsintegerrequired
conversionBpsBpsrequired
revenueMinorMinorUnitsrequired
pendingMinorMinorUnitsrequired
owedMinorMinorUnitsrequired
paidMinorMinorUnitsrequired
storeCreditMinorMinorUnitsrequired
currencyCurrencyCoderequired
linkstringrequired
createdAtTimestamprequired
payoutEmailstringrequired
notestringrequired
commissionsAffiliateCommission[]required
payoutsAffiliatePayout[]required
dailyobject[]required
- dateIsoDaterequired
- clicksintegerrequired
- conversionsintegerrequired

Example

curl -X PATCH "https://api.shopfa.st/v1/store/affiliates/aff_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "pending",
  "commissionBps": 0,
  "note": "string",
  "payoutEmail": "[email protected]",
  "name": "string",
  "newCustomersOnly": false,
  "reward": "cash"
}'

const res = await fetch('https://api.shopfa.st/v1/store/affiliates/aff_0123456789abcdefghjk', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "pending",
    "commissionBps": 0,
    "note": "string",
    "payoutEmail": "[email protected]",
    "name": "string",
    "newCustomersOnly": false,
    "reward": "cash"
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "PATCH",
    "https://api.shopfa.st/v1/store/affiliates/aff_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "status": "pending",
      "commissionBps": 0,
      "note": "string",
      "payoutEmail": "[email protected]",
      "name": "string",
      "newCustomersOnly": False,
      "reward": "cash"
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PATCH", "https://api.shopfa.st/v1/store/affiliates/aff_0123456789abcdefghjk", strings.NewReader(`{
  "status": "pending",
  "commissionBps": 0,
  "note": "string",
  "payoutEmail": "[email protected]",
  "name": "string",
  "newCustomersOnly": false,
  "reward": "cash"
}`))
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

affiliateId

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.

Pay every approved commission: from your ShopFast balance, or record a payment you made yourself

POST/v1/store/affiliates/{affiliateId}/payouts

Or name the store: POST /v1/stores/{storeId}/affiliates/{affiliateId}/payouts

marketing:writepayAffiliate

Parameters

affiliateIdaff_…pathrequired

Body

method"balance" | "external"required
referencestring

Response AffiliateDetail

idAffiliateIdrequired
namestringrequired
emailEmailrequired
codestringrequired
statusAffiliateStatusrequired
commissionBpsBps | nullrequired
effectiveBpsBpsrequired
newCustomersOnlybooleanrequired
effectiveNewCustomersOnlybooleanrequired
rewardAffiliateReward | nullrequired

17 more fields

effectiveRewardAffiliateRewardrequired
clicksintegerrequired
conversionsintegerrequired
conversionBpsBpsrequired
revenueMinorMinorUnitsrequired
pendingMinorMinorUnitsrequired
owedMinorMinorUnitsrequired
paidMinorMinorUnitsrequired
storeCreditMinorMinorUnitsrequired
currencyCurrencyCoderequired
linkstringrequired
createdAtTimestamprequired
payoutEmailstringrequired
notestringrequired
commissionsAffiliateCommission[]required
payoutsAffiliatePayout[]required
dailyobject[]required
- dateIsoDaterequired
- clicksintegerrequired
- conversionsintegerrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/affiliates/aff_0123456789abcdefghjk/payouts" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "balance",
  "reference": ""
}'

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

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/affiliates/aff_0123456789abcdefghjk/payouts", strings.NewReader(`{
  "method": "balance",
  "reference": ""
}`))
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

affiliateId

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.