🧑‍🏫

【Shopify.dev和訳】API Examples/Gift cards

2021/09/18に公開

API

Shopify

tech

この記事について

この記事は、API Examples/Gift cardsの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

GraphQL Admin API を使用してギフトカードを管理する

ギフトカードは、販売者が店舗を通じて販売できる商品です。顧客は、購入の支払い方法としてギフトカードを使用します。このチュートリアルでは、GraphQL Admin APIを使用して、ストアのギフトカードを作成、取得、更新、および無効化する方法を示します。

ギフトカードの仕組み

ギフトカードは特別な種類の商品であり、別の支払い方法です。その価値は、オンラインストアからの将来の注文に対する支払いとして使用できます。

各ギフトカードには、チェックアウト時に入力される一意のコードがあります。その残高は、複数のチェックアウトで利用できます。オプションで、ギフトカードコードを特定の顧客に割り当てることができます。

ギフトカードを作成した後は、ギフトカードコードを更新できません。更新できるのは、顧客、有効期限、メモ、およびテンプレートのサフィックスのみです。ギフトカードコードは、作成後に取得できません。取得できるのは最後の 4 文字のみです。

要件

アプリはプライベートまたはカスタムのいずれかであり、ShopifyPlusストアにインストールされている必要があります。
GraphQL Admin および RESTAdmin APIの開始ガイドを完了し、API で認証されました。
ストアの Shopify 管理者でギフトカード機能を有効にしました。

Scopes

GraphQL クエリとミューテーションを使用するには、アプリで Shopify ストアの次のアクセススコープをリクエストする必要があります。

read_gift_cards：アプリがギフトカードを読み取れるようにします。
write_gift_cards:アプリがギフトカードを作成できるようにします。

ギフトカードを作成する

新しいギフトカードを作成するには、giftCardCreateミューテーションを実行します。返されるフィールドには、ギフトカードの ID(id)、編集されたギフトカードコード(maskedCode)、ギフトカードが作成されたときのタイムスタンプ(createdAt)、および完全なギフトカードコード(giftCardCode)が含まれます。次の例では、ギフトカードの初期値が入力変数として提供されています。

リクエストの例

POST /admin/api/2021-04/graphql.json

mutation giftCardCreate($input: GiftCardCreateInput!) {
  giftCardCreate(input: $input){
    giftCard{
      id
      maskedCode
      createdAt
    }
    giftCardCode
    userErrors{
      code
      field
    }
  }
}

Input variables

{
  "input": {
    "initialValue": 100
  }
}

応答

JSON response

{
  "data": {
    "giftCardUpdate": {
      "giftCard": {
        "id": "gid://shopify/GiftCard/1234",
        "maskedCode": "•••• •••• •••• be55",
        "createdAt": "2021-03-03T21:23:17Z",
        "expiresOn": "2025-12-26"
      },
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10
    }
  }
}

ギフトカードを取得する

既存のギフトカードを取得するには、QueryRootでギフトカードをクエリします。次の例では、応答本文は最初の 5 枚のギフトカードとそれに対応する ID を返します。

リクエストの例

POST /admin/api/2021-04/graphql.json

query {
  giftCards(first: 5) {
    edges {
      node {
        id
      }
    }
  }
}

応答

JSON response

{
  "data": {
    "giftCards": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/GiftCard/1234"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/2345"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/3456"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/4567"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/5678"
          }
        },
      ]
    }
  },
}

ギフトカードを更新する

ギフトカードを更新するには、giftCardUpdateミューテーションを実行できます。たとえば、ギフトカードの有効期限を更新する場合は、ミューテーションの入力変数としてギフトカード ID（id）と新しい有効期限（expiresOn）を指定できます。次の例では、ギフトカードの有効期限が 2025 年 12 月 26 日に更新されています。

リクエストの例

POST /admin/api/2021-04/graphql.json

mutation giftCardUpdate($id: ID!, $input: GiftCardUpdateInput!) {
  giftCardUpdate(id: $id, input: $input){
    giftCard{
      id
      maskedCode
      createdAt
      expiresOn
    }
    userErrors{
      field
    }
  }
}

Input variables



Copy
{
  "id": "gid://shopify/GiftCard/1234",
  "input": {
    "expiresOn": "2025-12-26"
  }
}

応答

JSON response

{
  "data": {
    "giftCardUpdate": {
      "giftCard": {
        "id": "gid://shopify/GiftCard/1234",
        "maskedCode": "•••• •••• •••• be55",
        "createdAt": "2021-03-03T21:23:17Z",
        "expiresOn": "2025-12-26"
      },
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10
    }
  }
}

ギフトカードを無効にする

ギフトカードを無効にするには、giftCardDisableミューテーションを実行し、無効にするギフトカードの ID を指定します。ギフトカードを無効にすると、販売者は店舗でギフトカードを販売できなくなり、顧客はギフトカードを使用して購入できなくなります。

リクエストの例

POST /admin/api/2021-04/graphql.json

mutation giftCardDisable($id: ID!) {
  giftCardDisable(id: $id){
    giftCard{
      id
      maskedCode
      createdAt
      expiresOn
    }
    userErrors{
      field
    }
  }
}

Input variables

{
  "id": "gid://shopify/GiftCard/1234"
}

応答

JSON response

{
  "data": {
    "giftCardDisable": {
      "giftCard": {
        "id": "gid://shopify/GiftCard/1234",
        "maskedCode": "•••• •••• •••• be55",
        "createdAt": "2021-03-03T21:23:17Z",
        "expiresOn": "2025-12-26"
      },
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10
    }
  }
}

次のステップ

ギフトカードに関するよくある質問への回答を入手してください。
ステータスを使用してギフトカードなどの商品を識別、フィルタリング、管理する方法を学びましょう。
カスタム画像を使用してギフトカードをパーソナライズする方法を学びます。

Shopify アプリのご紹介

Discussion

ログインするとコメントできます