Gift Card Hero REST API¶
REST API を使うと、CRM、分析ダッシュボード、ロイヤルティプラットフォーム、フルフィルメントサービスなどの外部システムから、プログラムでギフトカードを管理できます。
ベース URL¶
すべての API リクエストは、次のベース URL を使用します:
https://gifthero.syncu.be/api/external
認証¶
すべてのリクエストには、Authorization ヘッダーに Bearer トークンを含める必要があります:
Authorization: Bearer YOUR_API_TOKEN
API トークンを取得するには、左側のナビゲーションで For developers に移動し、Enable REST API にチェックを入れて保存します。Send me access token をクリックすると、ページに表示されているストアの連絡先メールアドレスにトークンが送信されます。
トークンは、置き換えるか無効化するまで期限切れになりません。パスワードと同様に扱ってください。連携先のシークレット設定に保存し、チャット、チケット、共有ドキュメントに貼り付けないでください。
API トークンの管理¶
トークンは1つだけです。 ストアの API トークンは1つだけです。API を呼び出すすべてのシステム（POS、CRM、パートナーのサービスなど）が、同じトークンを使用します。
新しいトークンを送信すると、古いトークンは置き換えられます。 Send me access token をクリックするたびに新しいトークンが発行され、以前のトークンは直ちに使えなくなります。すべての連携先を、すぐに新しいトークンに更新してください。トークンを再確認するだけの場合は、新しいトークンを送信するのではなく、以前のメールを探してください。
トークンの無効化。 トークンが漏えいした可能性がある場合や、そのトークンを持っていたパートナーとの取引が終了した場合は、For developers ページで Revoke access token をクリックし、確定してください。トークンはすぐに使えなくなり、新しいトークンは発行されません。準備ができたら、Send me access token をクリックして新しいトークンを発行します。
REST API をオフにする。 Enable REST API をオフにして保存すると、トークンも無効化されます。API を再びオンにした後は、新しいトークンを自分宛に送信してください。
連携先に表示されるもの。 置き換えられたトークンまたは無効化されたトークンを使ったリクエストには、401 が返されます:
{
"error": {
"statusCode": 401,
"name": "UnauthorizedError",
"message": "Error verifying token : The token has been revoked or replaced."
}
}
対処方法は常に同じです。現在のトークンを Authorization ヘッダーに設定してください。
トークン ID が導入される前に発行されたトークンは、新しいトークンを送信するか、無効化するまで、引き続き使用できます。
その他の認証エラー:
| ステータス | 意味 |
|---|---|
401 |
Authorization ヘッダーがないか、Bearer 形式ではないか、トークンが無効です |
402 |
ストアに有効な Gift Card Hero プランがありません |
エンドポイント¶
ギフトカードの一覧¶
GET /gift-cards
パラメーター:
| パラメーター | 型 | 説明 |
|---|---|---|
status |
文字列 | ギフトカードのステータスで絞り込みます |
limit |
整数 | 結果の最大件数（最大 250） |
since_id |
文字列 | 指定したギフトカード ID より後の結果を返します |
fields |
文字列 | 含めるフィールドのカンマ区切りのリスト |
このリクエストは Shopify のギフトカード一覧に渡されるため、Shopify 独自のパラメーターも適用されます。レスポンスの各カードには、recipient オブジェクト（id、email、name）または null が含まれます。Gift Card Hero が完全なコードを記録している場合は、code フィールドも含まれます（重要な注意事項 を参照）。
HEAD /gift-cards リクエストは、本文なしで 200 を返します。一部の HTTP クライアントは、事前確認としてこれを使用します。
トランザクション付きのギフトカード一覧¶
GET /gift-cards/transactions
ギフトカードを新しい順に返します。各カードには、直近最大 50 件のトランザクションが含まれます。カーソルベースのページネーションに対応しています。
ページネーション:
| パラメーター | 型 | 説明 |
|---|---|---|
limit |
整数 | 1ページあたりのギフトカード数（デフォルトは 50） |
page_info |
文字列 | 次のページの結果を示すカーソル |
フィルター:
| フィルター | 型 | 説明 |
|---|---|---|
query |
文字列 | 検索クエリ（Shopify のギフトカード検索構文） |
balance_status |
文字列 | full、partial、empty、full_or_partial のいずれか |
created_at |
文字列 | 作成日で絞り込みます |
expires_on |
文字列 | 有効期限日で絞り込みます |
source |
文字列 | manual、purchased、api_client のいずれか |
status |
文字列 | disabled、enabled、expired、expiring のいずれか |
initial_value |
文字列 | 初期金額で絞り込みます |
id |
文字列 | ギフトカード ID で絞り込みます |
複数のフィルターを組み合わせた場合、すべてのフィルターは AND 条件で適用されます。
レスポンス:
各ギフトカードには、id、balance、currency、initial_value、created_at、updated_at、disabled_at、customer_id、recipient、note、expires_on、template_suffix、last_characters、order_id、transactions、issued_by が含まれます。レスポンスにはギフトカードのコードは含まれません。各トランザクションには、id、amount（引き落としの場合は負の値）、processed_at、note、pos_user、pos_order_name が含まれます。
トランザクション ID:
transactions[].id は、ギフトカードのトランザクションの数値の Shopify ID です。gid://shopify/GiftCardDebitTransaction/… または gid://shopify/GiftCardCreditTransaction/… の GID 末尾の数字です。以前のバージョンの API では、ここは null を返していました。
POS フィールド:
Gift Card Hero POS で発行または利用されたギフトカードには、その操作を行ったレジ担当者の情報が含まれます。これらのフィールドは、標準のレスポンスに追加されます:
| フィールド | 型 | 説明 |
|---|---|---|
transactions[].pos_user |
オブジェクトまたは null | POS で行われた引き落としの場合は { "username": "woodgrove", "name": "Woodgrove" }。それ以外は null |
transactions[].pos_order_name |
文字列または null | その引き落としについて POS で入力された注文名（ある場合）。それ以外は null |
issued_by |
オブジェクトまたは null | POS で発行されたカードの場合は { "username", "name", "issued_at" }。それ以外は null |
POS のアクティビティログには Shopify のトランザクション ID が保存されないため、引き落としは、カード、金額、時刻によって POS での利用と照合されます（利用は、トランザクションの数秒前から1分後までの間にログされている必要があります）。オンラインの支払い、Shopify 管理画面での変更、対応する POS の記録がない引き落としには null が設定されます。POS ユーザーが後に削除されている場合、name は null になります。
1枚のギフトカードを取得する¶
GET /gift-cards/{gift_card_id}
ID を指定して、1枚のギフトカードの詳細を返します。recipient と、Gift Card Hero が保持している場合は code が含まれます。
ギフトカードを作成する¶
POST /gift-cards
リクエストボディ:
{
"note": "Loyalty reward",
"initial_value": "50.00",
"code": "ABCD-EFGH-IJKL-MNOP",
"template_suffix": "custom"
}
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
note |
文字列 | いいえ | ギフトカードの社内用メモ |
initial_value |
文字列 | はい | 初期残高 |
code |
文字列 | いいえ | 任意のギフトカードコード（一意である必要があります。省略すると自動生成されます） |
template_suffix |
文字列 | いいえ | Shopify のテンプレートサフィックス |
customer_id |
整数 | いいえ | カードを所有する Shopify の顧客 |
email |
文字列 | いいえ | 顧客のメールアドレス。customer_id が送信されていない場合に使用されます。Gift Card Hero は顧客を検索するか、gifthero:import のタグを付けて新規作成します |
リクエストボディは Shopify のギフトカードエンドポイントに渡されます。このエンドポイントは expires_on などの追加フィールドも受け付けます。レスポンスは Shopify のギフトカードで、完全な code が含まれます。
重要: 必要な場合は、作成時のレスポンスから完全なコードを保存してください。後のレスポンスに完全な
codeが含まれるのは、Gift Card Hero がそのコードを記録しているカードだけです。それ以外の場合は、末尾4文字（last_characters）のみが返されます。
ギフトカードの残高を更新する¶
PUT /gift-cards/{gift_card_id}/balance
リクエストボディ:
{
"balance": "100.00"
}
ギフトカードの残高を、指定した値に設定します。"+25.00" や "-10.00" のように符号を付けた値は、代わりに現在の残高への調整として適用されます。残高が変わらない場合は、現在の残高が返され、何も記録されません。ストアで Increase limit がオンの場合、チャージ額は Shopify の標準のギフトカード上限を超えることができます。
これは残高の修正です。お客様への通知は送信されず、店舗も記録されません。お客様がレジでカードを使う場合は、代わりに ギフトカードを利用する を使用してください。
ギフトカードを利用する¶
POST /gift-cards/{gift_card_id}/redeem
Shopify のチェックアウトの外で、サードパーティの POS またはレジアプリからギフトカードを引き落とします（利用処理）。カード保有者は、店舗名を含むストアの利用通知（メールまたは SMS）を受け取ります。Redemption notifications の設定で Who gets notified が指定されている場合は、代わりに購入者が受け取るか、両方が受け取ります。また、利用は店舗名とともに Gift Card Hero のレポートに表示されます。Shopify の giftCardDebit を直接呼び出す代わりに、この方法を使用してください。直接の引き落としでは、店舗名も通知も送信されません。
利用と残高の更新の違い: 誰にも通知せずに残高を値に設定する場合は、ギフトカードの残高を更新する を使用してください。お客様がカードを使い、通知と店舗の記録を残したい場合は、ギフトカードを利用する を使用してください。
リクエストボディ:
{
"amount": "1500.00",
"branch": "Westgate",
"reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
"note": "Table 12"
}
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
amount |
文字列 | はい | 利用する金額です。0より大きく、カードの残高以下で、カードの通貨で指定し、小数点以下は2桁までとします |
branch |
文字列 | はい | 店舗名または拠点名です。利用メールと SMS（Redemption notifications で Include the store location がオンの場合）およびレポートに表示されます |
reference |
文字列 | はい | この利用に対する一意の ID です。最大 255 文字。再試行と重複 を参照してください |
note |
文字列 | いいえ | Shopify のギフトカードのトランザクションに記録されます。Gift Card Hero はメモに [ref:<reference>] を追加するため、API によるすべての利用を、Shopify 管理画面で対応する reference と照合できます |
レスポンス（200）:
{
"id": 661944893757,
"last_characters": "7nsf",
"amount": "1500.00",
"currency": "KES",
"balance_before": "5090.00",
"balance": "3590.00",
"branch": "Westgate",
"reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
"processed_at": "2026-10-12T10:30:00Z",
"notification": "queued",
"duplicate": false
}
| フィールド | 説明 |
|---|---|
notification |
queued: 利用通知がストアの Redemption notifications 設定に渡されました。送信するかどうかは、この設定によって決まります（すべての利用、またはカードの残高を使い切った場合のみ）。disabled: ストアで利用通知がオフになっています |
duplicate |
この reference がすでに処理済みで、レスポンスが元の結果である場合は true |
エラー:
エラーは通常の形式で返されます: {"error": {"statusCode": 422, "name": "...", "message": "..."}}。
| ステータス | 意味 | 対処方法 |
|---|---|---|
400 |
amount、branch、reference のいずれかがないか、無効です |
リクエストボディを修正してください |
401 |
トークンがないか、無効か、無効化されているか、新しいトークンに置き換えられています | Authorization ヘッダーを確認してください。トークンが無効化または置き換えられている場合は、新しいトークンを取得してください |
403 |
アプリにストアのアクセススコープが不足しています | ストアのオーナーが、Shopify 管理画面でアプリの更新された権限を承認する必要があります |
404 |
ギフトカードが見つかりません | ギフトカード ID を確認してください |
409 |
この reference が、別のカードまたは金額ですでに使用されているか、この reference のリクエストがまだ処理中です |
新しい利用の場合は、新しい reference を使用してください。リクエストがまだ処理中の場合は、数秒待ってから、同じ reference で再試行してください |
422 |
カードが無効または期限切れであるか、金額が残高を超えています。message に理由が示されます。残高は変わりません |
原因を修正してください。reference は使用済みになっていないため、同じ reference で再試行してください |
429 |
Shopify がストアのリクエストを制限しています | 間隔を空けて、同じ reference で再試行してください |
500 |
Shopify で結果を確認できませんでした | 同じ reference で再試行してください。カードが二重に引き落とされることはありません |
失敗したリクエスト（404 または 422）では、reference は使用済みになりません。
再試行と重複¶
利用ごとに1つの reference を生成し、同じ利用を再試行する場合にのみ再利用してください。リクエストがタイムアウトした場合やネットワークで失敗した場合は、同じ reference で再試行してください。これは常に安全です。カードが二重に引き落とされることはなく、"duplicate": true を伴って元の結果が返されます。
ギフトカードを更新する¶
PUT /gift-cards/{gift_card_id}
更新できるのは次のフィールドのみです:
| フィールド | 型 | 説明 |
|---|---|---|
expires_on |
文字列 | 有効期限日 |
note |
文字列 | 社内用メモ |
template_suffix |
文字列 | Shopify のテンプレートサフィックス |
customer_id |
整数 | カードを所有する Shopify の顧客。カードを作成するときと同様に、代わりに email を送信することもできます |
Gift Card Hero がコードを記録している場合、レスポンスには code が含まれます。
ギフトカードを無効にする¶
POST /gift-cards/{gift_card_id}/disable
ギフトカードを完全に無効にします。この操作は元に戻せません。無効化されたギフトカードを返します。
ギフトカードを検索する¶
GET /gift-cards/search
パラメーター:
| パラメーター | 型 | 説明 |
|---|---|---|
order |
文字列 | 並び順 |
query |
文字列 | 検索クエリ（例: last_characters:mnop）。受取人に送られたカードを探すには recipient:name@example.com を使用します |
limit |
整数 | 結果の最大件数 |
fields |
文字列 | 含めるフィールドのカンマ区切りのリスト |
インデックス化されたフィールド（検索クエリで利用可能）:
created_at, updated_at, disabled_at, balance, initial_value, amount_spent, last_characters
注文にギフトカードコードを割り当てる¶
POST /gift-cards/assign-to-order
アプリの外でコードを生成しているストア向けに、独自のギフトカードコードを Shopify の注文に割り当てます。Regular products as gift cards の設定で Skip gift codes generation がオンの場合にのみ動作します。オフの場合は 400 を返します。また、orderId が数値でない場合、またはストアにすでに同じコードが存在する場合も 400 を返します。注文が見つからない場合は 404 を返します。
1つのコードの割り当てと、複数のコードの割り当ての両方に対応しています。
1つのコード:
{
"orderId": "1234567890",
"giftCode": "ABCD-EFGH-IJKL-MNOP"
}
複数のコード:
{
"orderId": "1234567890",
"giftCodes": [
{ "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" },
{ "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" }
]
}
レスポンス:
{
"scheduled": true
}
注文に処理するギフトカードがない場合、scheduled は false になります。
ページネーション¶
トランザクションのエンドポイントは、カーソルベースのページネーションを使用します。レスポンスには、次のページのカーソルを含む Link ヘッダーが含まれます:
Link: <https://gifthero.syncu.be/api/external/gift-cards/transactions?page_info=CURSOR>; rel="next"
最後のページには、このヘッダーはありません。Link ヘッダーから page_info の値を読み取り、同じフィルターとともに、次のリクエストのクエリパラメーターとして渡してください。次のページの URL には、すでにこれらが含まれています。
重要な注意事項¶
- コードの一意性 — 任意のコードでギフトカードを作成する場合、各コードは一意である必要があります。重複したコードを送信すると、API はエラーを返します。
- コードの表示 — 作成時のレスポンスには、完全なコードが含まれます。後のレスポンスで
codeフィールドが表示されるのは、Gift Card Hero が完全なコードを記録しているカードだけです（Gift Card Hero が生成したカードと、割り当てたコード）。それ以外の場合は、末尾4文字（last_characters）のみが返されます。トランザクションのエンドポイントは、コードを返しません。 - 利用の再試行 — ギフトカードを利用する場合は、必ず一意の
referenceを送信し、タイムアウト後は同じreferenceで再試行してください。再試行と重複 を参照してください。 - レート制限 — リクエストは Shopify に渡されるため、ストアに対する Shopify の制限が適用されます。
429レスポンスを受け取った場合は、間隔を空けて再試行してください。 - Postman コレクション —
/gift-cards/transactionsと/gift-cards/assign-to-orderを除く、ギフトカードのエンドポイントを含みます。
Postman コレクション¶
API をすばやく試せるよう、Postman コレクションをダウンロードしてください: