🧑‍🏫

【Shopify.dev和訳】API Examples/Discounts

2021/09/18に公開約21,700字

この記事について

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

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

Shopify アプリのご紹介

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

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

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

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Admin API による割引の作成と管理

このガイドでは、GraphQL Admin API を使用して割引を作成および取得する方法について説明します。2 種類の割引(自動割引とコード割引)の例と、それぞれのタイプで推奨されるベストプラクティスを紹介しています。

スキーマの完全なリストは、GraphQL Admin API リファレンスを参照してください。

GraphQL に慣れていない場合は、「Getting started with the GraphQL Admin and REST Admin APIs」ガイドまたは「The GraphQL Learning Kit」を参照してください。


必要条件

ここで説明している mutation には、write_discounts権限が必要です。
ここで説明されているクエリにはread_discountsパーミッションが必要です。


自動割引の作成

自動割引とは、前提条件を満たした場合にカートに自動的に適用される割引を作成・管理するための、GraphQL のオブジェクトとミューテーションのセットを指します。この方法は、GraphQL Admin API でのみ利用できます。

次の例は、2 種類の自動割引を示しています。

「Buy X Get Y」または「Spend X Get Y」の自動割引について

この例では、1 つの商品がカートに入ったときに適用される自動 Buy One Get One 割引を作成しています。この例では、最初の商品と同じ商品であれば、カートの 2 番目の商品に 100%の割引を適用します。

mutation {
  discountAutomaticBxgyCreate(
    automaticBxgyDiscount: {
      title: "bxgy test"
      startsAt: "2016-01-01"
      endsAt: "2019-04-18T02:38:45Z"
      usesPerOrderLimit: "1"
      customerBuys: {
        value: {
          #量、金額を受け付ける
          quantity: "1"
        }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
      customerGets: {
        value: { discountOnQuantity: { quantity: "1", effect: { percentage: 1.00 } } }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
    }
  ) {
    userErrors {
      field
      message
      code
    }
    automaticDiscountNode {
      automaticDiscount {
        ... on DiscountAutomaticBxgy {
          title
          summary
          status
        }
      }
    }
  }
}

この例に基づいて、特定のタイプの割引を提供するためにいくつかの異なる変更を行うことができます。

  • 割引額を変更したい場合は、customerGets.value.discountOnQuantity.effect.percentを編集します。
  • 割引を別のアイテムに適用したい場合は、customerGets.items.productsToAdd および customerGets.items.productsToRemove を使用して権限を更新します。
  • すべてのアイテムに割引を適用したい場合は、特定の製品 ID ではなく customerGets.items.all を使用してください。
  • 顧客がどの商品を購入しても割引を受けられるようにしたい場合は、特定の商品ではなく、customerBuys.items.all の前提条件を trueにします。

パーセンテージまたは固定額の自動割引

この例では、1 つの商品がカートに入ったときにいつでも適用される 10%の自動割引を作成する方法を示します。percentageの入力には、0 から 1 までの値が必要です。以下の例では、0.10が 10%の割引を表します。100%割引の場合は1.0、50%割引の場合は0.5となります。

mutation {
  discountAutomaticBasicCreate(
    automaticBasicDiscount: {
      title: "AutoDiscountTest"
      startsAt: "2017-04-18T02:38:45Z"
      endsAt: "2018-04-18T02:38:45Z"
      customerGets: {
        value: {
          #パーセンテージ、割引額、数量割引を選択可能
          percentage: 0.10
        }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
      minimumRequirement: {
        #量、またはサブトータを受け入れる
        quantity: { greaterThanOrEqualToQuantity: "1" }
      }
    }
  ) {
    userErrors {
      field
      message
      code
    }
    automaticDiscountNode {
      automaticDiscount {
        ... on DiscountAutomaticBasic {
          title
          shortSummary
          summary
          minimumRequirement {
            ... on DiscountMinimumQuantity {
              quantity: greaterThanOrEqualToQuantity
            }
            ... on DiscountMinimumSubtotal {
              subtotal: greaterThanOrEqualToSubtotal {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

コードディスカウントの作成

コード・ディスカウントとは、固有のコードを含むディスカウントを作成・管理するための、GraphQL のオブジェクトとミューテーションのセットを指す。コード割引は、チェックアウト時に顧客が手動でコードを適用することで、特定の割引を利用できるようにします。このメソッドは、GraphQL Admin API でのみ利用できます。

以下の例では、3 種類のコードディスカウントを紹介しています。

「Buy X Get Y」または「Spend X Get Y」のコード割引

この例では、顧客がチェックアウト時にコードを入力する必要のある「Spend $100 Get One」割引を作成する方法を示しています。この例では、すべてのお客様にこのコードを使用していただき、同じ商品に対して「100 ドル使って 1 つ」の割引を提供しています。また、元の商品とは別の商品に適用されるように割引を変更することもできます。

mutation {
  discountCodeBxgyCreate(
    bxgyCodeDiscount: {
      title: "code bxgy test"
      startsAt: "2016-01-01"
      endsAt: "2019-04-18T02:38:45Z"
      usesPerOrderLimit: 1
      code: "TESTCODE1001234"
      customerSelection: { all: true }
      customerBuys: {
        value: { amount: 100 }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
      customerGets: {
        value: { discountOnQuantity: { quantity: "1", effect: { percentage: 1.00 } } }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
    }
  ) {
    userErrors {
      field
      message
      code
    }
    codeDiscountNode {
      id
      codeDiscount {
        ... on DiscountCodeBxgy {
          title
          summary
          status
          codes(first: 100) {
            edges {
              node {
                code
              }
            }
          }
        }
      }
    }
  }
}

パーセンテージまたは定額制の割引コード

この例では、一律のパーセンテージまたは定額の割引を、お客様がチェックアウト時に使用できるコードと関連付ける方法を示します。ここでは、特定の商品を対象とした$1.00 オフの割引を作成します。

mutation {
  discountCodeBasicCreate(
    basicCodeDiscount: {
      title: "code basic test"
      startsAt: "2019-01-01"
      endsAt: "2020-01-01"
      usageLimit: 10
      appliesOncePerCustomer: true
      customerSelection: { all: true }
      code: "123456"
      customerGets: {
        value: { discountAmount: { amount: 1.00, each: true } }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
    }
  ) {
    userErrors {
      field
      message
      code
    }
    codeDiscountNode {
      id
      codeDiscount {
        ... on DiscountCodeBasic {
          title
          summary
          status
          codes(first: 10) {
            edges {
              node {
                code
              }
            }
          }
        }
      }
    }
  }
}

送料無料コード割引

この例では、送料無料の割引をコードに関連付け、そのコードを使用すると顧客に送料無料を付与する方法を示しています。この例では、customerSelection.customerSavedSearches に保存されている顧客のうち、カナダ出身の顧客に対して割引を適用しています。すべての国に割引を適用したい場合は、destination.countires.adddestination.all を true に設定したものに置き換えることができます。送料無料にしたい国を指定した場合、ショップにその国の配送地域が設定されていないと機能しないことに注意してください。

mutation {
  discountCodeFreeShippingCreate(
    freeShippingCodeDiscount: {
      code: "FSCODE"
      title: "Free Shipping"
      startsAt: "2019-05-15T15:02:49Z"
      destination: { countries: { add: [CA] } }
      customerSelection: { customerSavedSearches: { add: ["gid://shopify/SavedSearch/1"] } }
    }
  ) {
    userErrors {
      field
      message
      code
    }
    codeDiscountNode {
      id
      codeDiscount {
        __typename
        ... on DiscountCodeFreeShipping {
          title
          status
          codes(first: 10) {
            edges {
              node {
                code
              }
            }
          }
        }
      }
    }
  }
}

ディスカウントの管理

API を使って、現在の割引を管理したり、変更したりすることができます。

ショップの自動割引の問い合わせ

GraphQL のクエリでは、一度に複数のオブジェクトを返すことができます。次の例では、最初の 10 個の自動割引コードを要求し、それらがBxGyタイプかBasicタイプかの詳細を返しています。

{
  automaticDiscountNodes(first: 10) {
    edges {
      node {
        id
        automaticDiscount {
          __typename
          ... on DiscountAutomaticBxgy {
            status
            title
          }
          ... on DiscountAutomaticBasic {
            status
            title
          }
        }
      }
    }
  }
}

特定の自動割引の照会

特定の自動割引を照会するには、その ID が必要です。次の例は、フラグメントと呼ばれる概念を使用しているため、複雑なクエリに見えるかもしれません。フラグメントを使用すると、条件に一致する場合にのみ情報を返すクエリを作成できます。この例では、自動割引の詳細を事前に知らない場合に備えて、どのようなタイプの割引であっても、この割引に関するすべての可能な情報を要求しています。

{
  automaticDiscountNode(id: "gid://shopify/DiscountAutomaticNode/298192273430") {
    id
    automaticDiscount {
      __typename
      ... on DiscountAutomaticBxgy {
        createdAt
        customerBuys {
          items {
            __typename
            ... on DiscountProducts {
              productVariants(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
              products(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
            ... on DiscountCollections {
              collections(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
            ... on AllDiscountItems {
              allItems
            }
          }
          value {
            __typename
            ... on DiscountQuantity {
              quantity
            }
            ... on DiscountPurchaseAmount {
              amount
            }
          }
        }
        customerGets {
          items {
            __typename
            ... on DiscountProducts {
              productVariants(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
              products(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
            ... on DiscountCollections {
              collections(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
            ... on AllDiscountItems {
              allItems
            }
          }
          value {
            __typename
            ... on DiscountOnQuantity {
              effect {
                ... on DiscountPercentage {
                  percentage
                }
              }
              quantity {
                quantity
              }
            }
            ... on DiscountAmount {
              amount {
                amount
                currencyCode
              }
              each
            }
            ... on DiscountPercentage {
              percentage
            }
          }
        }
        startsAt
        endsAt
        status
        summary
        title
        usageCount
        title
      }
      ... on DiscountAutomaticBasic {
        createdAt
        customerGets {
          items {
            __typename
            ... on DiscountProducts {
              productVariants(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
              products(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
            ... on DiscountCollections {
              collections(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
            ... on AllDiscountItems {
              allItems
            }
          }
          value {
            __typename
          }
        }
        minimumRequirement {
          __typename
        }
        shortSummary
        startsAt
        endsAt
        status
        summary
        title
        usageCount
        title
      }
    }
    events(first: 10) {
      edges {
        node {
          appTitle
          attributeToApp
          attributeToUser
          createdAt
          criticalAlert
          id
          message
          __typename
        }
      }
    }
  }
}

自動割引の有効化と無効化

自動割引を有効にしたり無効にしたりするには、discountAutomaticActivateまたはdiscountAutomaticDeactivateという変異を使用します。必要な入力は、アクションを実行する自動割引の ID のみです。

mutation {
  discountAutomaticActivate(id: "gid://shopify/DiscountAutomaticNode/298196369430") {
    automaticDiscountNode {
      automaticDiscount {
        __typename
        ... on DiscountAutomaticBxgy {
          status
          title
        }
        ... on DiscountAutomaticBasic {
          status
          title
        }
      }
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}
mutation {
  discountAutomaticDeactivate(id: "gid://shopify/DiscountAutomaticNode/298203152406") {
    automaticDiscountNode {
      automaticDiscount {
        __typename
        ... on DiscountAutomaticBxgy {
          status
          title
        }
        ... on DiscountAutomaticBasic {
          status
          title
        }
      }
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}

ショップのコード割引の問い合わせ

次の例は、あるショップの基本的なコード割引を問い合わせる方法です。他の GraphQL クエリと同様に、必要な詳細情報だけをリクエストすることで、短いクエリにすることができます。次の例では、すべてのフィールドについて説明しますので、2 回にわたって説明する必要はありません。

{
  codeDiscountNode(id: "gid://shopify/DiscountCodeNode/4272958227") {
    id
    events(first: 10) {
      edges {
        node {
          appTitle
          attributeToApp
          attributeToUser
          createdAt
          criticalAlert
          id
          message
          __typename
        }
      }
    }
    codeDiscount {
      __typename
      ... on DiscountCodeBasic {
        appliesOncePerCustomer
        asyncUsageCount
        codeCount
        codes(first: 10) {
          edges {
            node {
              code
            }
          }
        }
        createdAt
        customerGets {
          items {
            __typename
            ... on DiscountProducts {
              products(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
          }
          value {
            __typename
            ... on DiscountOnQuantity {
              effect {
                __typename
                ... on DiscountPercentage {
                  percentage
                }
              }
              quantity {
                quantity
              }
            }
          }
        }
        customerSelection {
          __typename
          ... on DiscountCustomerAll {
            allCustomers
          }
        }
        endsAt
        shortSummary
        startsAt
        status
        summary
        title
        usageLimit
      }
    }
  }
}

特定の割引コードの照会

自動割引と同様に、特定のコードを ID で照会し、必要な情報のみを要求することができます。以下は、基本的な割引コードに可能なすべてのフィールドの例です。次の例では、DiscountCodeBasicフラグメントをDiscountCodeBxgyまたはDiscountCodeFreeShippingに置き換えることができます。これらはいずれもリターン・フィールドに若干の違いがありますが、基本的なフォーマットは同じです。

{
  codeDiscountNode(id: "gid://shopify/DiscountCodeNode/4272958227") {
    id
    events(first: 10) {
      edges {
        node {
          appTitle
          attributeToApp
          attributeToUser
          createdAt
          criticalAlert
          id
          message
          __typename
        }
      }
    }
    codeDiscount {
      __typename
      ... on DiscountCodeBasic {
        appliesOncePerCustomer
        asyncUsageCount
        codeCount
        codes(first: 10) {
          edges {
            node {
              code
            }
          }
        }
        createdAt
        customerGets {
          items {
            __typename
            ... on DiscountProducts {
              products(first: 10) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
          }
          value {
            __typename
            ... on DiscountOnQuantity {
              effect {
                __typename
                ... on DiscountPercentage {
                  percentage
                }
              }
              quantity {
                quantity
              }
            }
          }
        }
        customerSelection {
          __typename
          ... on DiscountCustomerAll {
            allCustomers
          }
        }
        endsAt
        shortSummary
        startsAt
        status
        summary
        title
        usageLimit
      }
    }
  }
}

自動割引の更新

割引の更新は、割引の作成と同じ方法で行われますが、ユニークな変異があります。BxGy 割引の場合はdiscountAutomaticBxgyUpdateを、ベーシック割引の場合はdiscountAutomaticBasicUpdateを使用してください。なお、割引コードを更新する際には、以下の例のように、productsToAddproductsToRemoveを使って、明示的にタイトル付きの商品を追加・削除する必要があります。複数の商品をカンマで区切って渡すことで、複数の商品を追加・削除することができます。

mutation {
  discountAutomaticBxgyUpdate(
    id: "gid://shopify/DiscountAutomaticNode/298192470038"
    automaticBxgyDiscount: {
      title: "bxgy test3"
      startsAt: "2016-01-01"
      endsAt: "2019-04-18T02:38:45Z"
      usesPerOrderLimit: "1"
      customerBuys: {
        value: { quantity: "1" }
        items: {
          products: {
            productsToAdd: ["gid://shopify/Product/1536578748438"]
            productsToRemove: [
              "gid://shopify/Product/1536578748401"
              "gid://shopify/Product/1536578748400"
            ]
          }
        }
      }
      customerGets: {
        value: { discountOnQuantity: { quantity: "1", effect: { percentage: 1.00 } } }
        items: { products: { productsToAdd: ["gid://shopify/Product/1536578748438"] } }
      }
    }
  ) {
    userErrors {
      field
      message
      code
    }
    automaticDiscountNode {
      automaticDiscount {
        ... on DiscountAutomaticBxgy {
          title
          summary
          status
        }
      }
    }
  }
}

コード割引の更新

割引の更新は、割引の作成と同じ方法で行われますが、ユニークな変異があります。BxGy 割引の場合はdiscountCodeBxgyUpdate、basic 割引の場合はdiscountCodeBasicUpdate、Free Shipping 割引の場合はdiscountCodeFreeShippingUpdateを使用します。割引を更新したい場合は、更新したいコードの ID を渡す必要があります。また、更新したいフィールドのみを含める必要があることにも注意してください(以下の例では、タイトルのみを含めています)。

mutation {
  discountCodeBxgyUpdate(
    id: "gid://shopify/DiscountCodeNode/298191814678"
    bxgyCodeDiscount: { title: "code bxgy test, name updated" }
  ) {
    userErrors {
      field
      message
      code
    }
    codeDiscountNode {
      id
      codeDiscount {
        ... on DiscountCodeBxgy {
          title
          summary
          status
          codes(first: 100) {
            edges {
              node {
                code
              }
            }
          }
        }
      }
    }
  }
}

自動割引の削除

自動割引の削除に必要なのは、その ID だけです。

mutation {
  discountAutomaticDelete(id: "gid://shopify/DiscountAutomaticNode/298192502806") {
    deletedAutomaticDiscountId
    userErrors {
      code
      field
      message
    }
  }
}

自動割引の一括削除

ID の配列を指定して、自動割引コードを一括で削除する例を示します。

mutation {
  discountAutomaticBulkDelete(
    ids: [
      "gid://shopify/DiscountAutomaticNode/298192273430"
      "gid://shopify/DiscountAutomaticNode/298192371734"
    ]
  ) {
    job {
      done
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}

コード割引の一括有効化

同様に、discountCodeBulkActivatemutation を使用すると、コード割引を一括して有効にすることができます。

mutation {
  discountCodeBulkActivate(
    ids: [
      "gid://shopify/DiscountCodeNode/720334028961"
      "gid://shopify/DiscountCodeNode/720334127265"
      "gid://shopify/DiscountCodeNode/720334192801"
    ]
  ) {
    userErrors {
      field
      message
    }
    job {
      id
      done
    }
  }
}

ジョブステータスの確認

以前の一括割引操作が完了したかどうかを確認するには、mutation の返されたジョブを照会することができます。

query {
  job(id: "gid://shopify/Job/be5235b1-88d2-4d71-a7f3-d2dd00f061ef") {
    id
    done
  }
}

割引コードによるページネーション

GraphQL によるページネーションに慣れていない場合は、Shopify GraphQL Learning Kitを参照してください。ディスカウントオブジェクトの pageInfocursor パラメータの構造は、GraphQL の他の場所での構造と似ています。次の例は、これらのパラメータを使ったクエリのサンプルです。

{
  codeDiscountNodes(first: 10) {
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    edges {
      cursor
      node {
        id
        codeDiscount {
          __typename
        }
      }
    }
  }
}

Shopify アプリのご紹介

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

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

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

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

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