Gift cards

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

Gift cards with balances

GET/v1/store/gift-cards

Or name the store: GET /v1/stores/{storeId}/gift-cards

marketing:readlistGiftCards

Parameters

tab"all" | "active" | "used" | "expired" | "disabled"query
qstring | nullquery

Response ListGiftCardsResponse

itemsGiftCard[]required
countsGiftCardCountsrequired
outstandingMinorMinorUnitsrequired

Example

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

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

tabq

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

Issue a gift card. The full code is returned once, here

POST/v1/store/gift-cards

Or name the store: POST /v1/stores/{storeId}/gift-cards

marketing:writeissueGiftCard

Body

amountMinorintegerrequired
recipientEmailstring | nullrequired
recipientNamestring | nullrequired
notestringrequired
expiresAtstring | nullrequired
sendbooleanrequired
codestring | null

Response IssueGiftCardResponse

giftCardGiftCardrequired
codestringrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/gift-cards" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amountMinor": 100,
  "recipientEmail": "[email protected]",
  "recipientName": "string",
  "note": "string",
  "expiresAt": "2026-10-21T12:00:00.000Z",
  "send": false,
  "code": null
}'

const res = await fetch('https://api.shopfa.st/v1/store/gift-cards', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amountMinor": 100,
    "recipientEmail": "[email protected]",
    "recipientName": "string",
    "note": "string",
    "expiresAt": "2026-10-21T12:00:00.000Z",
    "send": false,
    "code": 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/gift-cards",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "amountMinor": 100,
      "recipientEmail": "[email protected]",
      "recipientName": "string",
      "note": "string",
      "expiresAt": "2026-10-21T12:00:00.000Z",
      "send": False,
      "code": None
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/gift-cards", strings.NewReader(`{
  "amountMinor": 100,
  "recipientEmail": "[email protected]",
  "recipientName": "string",
  "note": "string",
  "expiresAt": "2026-10-21T12:00:00.000Z",
  "send": false,
  "code": 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.

A gift card and its history

GET/v1/store/gift-cards/{giftCardId}

Or name the store: GET /v1/stores/{storeId}/gift-cards/{giftCardId}

marketing:readgetGiftCard

Parameters

giftCardIdgc_…pathrequired

Response GetGiftCardResponse

giftCardGiftCardrequired
transactionsGiftCardTransaction[]required

Example

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

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

giftCardId

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

Adjust the balance, disable or re-enable, or change the expiry

PATCH/v1/store/gift-cards/{giftCardId}

Or name the store: PATCH /v1/stores/{storeId}/gift-cards/{giftCardId}

marketing:writeupdateGiftCard

Parameters

giftCardIdgc_…pathrequired

Body

adjustMinorinteger | nullrequired
enabledbooleanrequired
expiresAtstring | nullrequired
notestringrequired

Response UpdateGiftCardResponse

giftCardGiftCardrequired
transactionsGiftCardTransaction[]required

Example

curl -X PATCH "https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "adjustMinor": 0,
  "enabled": false,
  "expiresAt": "2026-10-21T12:00:00.000Z",
  "note": "string"
}'

const res = await fetch('https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "adjustMinor": 0,
    "enabled": false,
    "expiresAt": "2026-10-21T12:00:00.000Z",
    "note": "string"
  }),
});
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/gift-cards/gc_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "adjustMinor": 0,
      "enabled": False,
      "expiresAt": "2026-10-21T12:00:00.000Z",
      "note": "string"
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PATCH", "https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk", strings.NewReader(`{
  "adjustMinor": 0,
  "enabled": false,
  "expiresAt": "2026-10-21T12:00:00.000Z",
  "note": "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

giftCardId

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 gift card that was never used (disable used ones so their history stays)

DELETE/v1/store/gift-cards/{giftCardId}

Or name the store: DELETE /v1/stores/{storeId}/gift-cards/{giftCardId}

marketing:writerole: marketing:writedeleteGiftCard

Parameters

giftCardIdgc_…pathrequired

Response Ok

okbooleanrequired

Example

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

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

giftCardId

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 or clear (null) the expiry date

PUT/v1/store/gift-cards/{giftCardId}/expiry

Or name the store: PUT /v1/stores/{storeId}/gift-cards/{giftCardId}/expiry

marketing:writerole: marketing:writesetGiftCardExpiry

Parameters

giftCardIdgc_…pathrequired

Body

expiresAtstring | nullrequired

Response SetGiftCardExpiryResponse

giftCardGiftCardrequired
transactionsGiftCardTransaction[]required

Example

curl -X PUT "https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk/expiry" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expiresAt": "2026-10-21T12:00:00.000Z"
}'

const res = await fetch('https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk/expiry', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "expiresAt": "2026-10-21T12:00:00.000Z"
  }),
});
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/gift-cards/gc_0123456789abcdefghjk/expiry",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "expiresAt": "2026-10-21T12:00:00.000Z"
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PUT", "https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk/expiry", strings.NewReader(`{
  "expiresAt": "2026-10-21T12:00:00.000Z"
}`))
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

giftCardId

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.

A signed link to the gift card page on the storefront (shows the balance; applies the card to the cart)

POST/v1/store/gift-cards/{giftCardId}/share

Or name the store: POST /v1/stores/{storeId}/gift-cards/{giftCardId}/share

marketing:writerole: marketing:writeshareGiftCard

Parameters

giftCardIdgc_…pathrequired

Response ShareGiftCardResponse

urlstringrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/gift-cards/gc_0123456789abcdefghjk/share" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

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

giftCardId

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 that sell gift cards

GET/v1/store/gift-cards/products

Or name the store: GET /v1/stores/{storeId}/gift-cards/products

marketing:readrole: marketing:readlistGiftCardProducts

Response ListGiftCardProductsResponse

itemsobject[]required
- productIdProductIdrequired
- namestringrequired
- statusstringrequired
- soldintegerrequired

Example

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

const res = await fetch('https://api.shopfa.st/v1/store/gift-cards/products', {
  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/gift-cards/products",
    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/gift-cards/products", 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 product that sells gift cards (one option per amount). Each unit bought issues a card

POST/v1/store/gift-cards/products

Or name the store: POST /v1/stores/{storeId}/gift-cards/products

marketing:writerole: catalog:writecreateGiftCardProduct

Body

namestringrequired
descriptionstring
amountsMinorinteger[]required

Response CreateGiftCardProductResponse

productIdProductIdrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/gift-cards/products" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "",
  "amountsMinor": [
    100
  ]
}'

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

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/gift-cards/products", strings.NewReader(`{
  "name": "string",
  "description": "",
  "amountsMinor": [
    100
  ]
}`))
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.