【Shopify GraphQL API徹底解説】顧客(Customer)と注文(Order)

この記事の所要時間： 11分

Graph APIは最初から全てを理解することが困難なので、範囲を決めて少しずつ理解していく必要があります。

【Shopify GraphQL API徹底解説】シリーズでは、Shopify GraphQL APIの仕様から、主要なオブジェクトを少しずつ読み解いていきます。

説明は記事内で完結しているので、シリーズの他の記事を参照しなくても理解できるようにしています。

今回解説するのはCustomerとOrderです。

どちらもShopify APIにおいて中心的な役割を果たします。

Customerにはマーチャントにとって有益なフィールドがいくつかあるので、活用しない手はありません。

Orderは商品、顧客、決済、税金、配送など、あらゆる文脈が組み合わさって構成されます。様々なオブジェクトのハブとなっているので、Shopify APIの全体像を把握するにはOrderオブジェクトへの理解が欠かせません。

CustomerとOrderの関係性

Customer(顧客)は、複数のOrder(注文)を持っています。

Order(注文)は、配送の注文を表すFulfillmentOrderや、商品バリエーションと注文数を表すLineItemや、お金のやりとりを表すOrderTransactionを持っています。

まずは、Customerの詳細から見ていきます。

Customer

Customerはショップに登録された顧客を表します。

Customerの主要フィールド

顧客アカウントとstateフィールド

マーチャントは顧客が顧客アカウントを作る必要があるかどうかを選択できます。

さらに具体的には、以下の3つのオプションから選びます。

1. Disabled・・・顧客はストアでアカウントを作ることができません。顧客は注文をするたびに決済情報や住所を入力します。顧客が”情報を保存する”を選択すると、入力情報はブラウザのCookieに保存されます。
2. Required・・・顧客はアカウントを作成しないと、商品を購入することができません。顧客は1度だけ情報を入力すれば、次回からは、入力ボックスが自動で埋められます。顧客は複数の住所を登録することもできるので便利です。このオプションは、卸売用のストアや、メンバー制のストアで使われることが多いです。
3. Optional・・・アカウントを作るか作らないかは、顧客に任されています。アカウントを作ると2回目の注文からは入力ボックスが自動で埋められます。アカウントを作らなかった場合の挙動は、Disableと同じです。

RequiredかOptionalを選択したマーチャントは、顧客に対して、アカウント作成を促す招待メールを送信することができます。

個別に送ることも、複数顧客に対して一気に送ることもできます。

stateフィールドのCustomerState型は、顧客の状態を表す列挙型です。

以下のいずれかの値をとります。

• ENABLED・・・顧客がアカウントを作成した。
• DISABLED・・・顧客がアカウントを持っていない。
• INVITED・・・顧客がアカウントを持っていないので、招待メールを送信した。
• DECLINED・・・顧客が招待メールを受け取り、アカウント作成を拒否した。

過去の注文に関するフィールド

Customerには過去の注文に関するフィールドがあります。

ordersCount, totalSpent, lastOrderなどです。

これらの情報と、Customerの注文自体の情報を組み合わせることで、有益な分析結果が得られるでしょう。

マーチャントはこれらの情報を通して、より顧客を理解することで、顧客と良い関係を築くことができます。

tagsフィールドとnoteフィールド

上記の表には載せませんでしたが、顧客自体の情報とは別に、マーチャントが顧客に関する情報を追記できるフィールドがあります。

tagsフィールドとnoteフィールドです。

tagsフィールドはString型のリストです。顧客をタグを使って分類することができます。

noteフィールドはString型です。顧客に関するメモをマーチャントが記すことができます。

Order

Orderは顧客の商品注文を表します。

Orderのフィールドは80個以上あり、主要オブジェクトの中で最も多いです。

Shopify APIにおいて中心的なオブジェクトであり、重要な概念が詰め込まれています。

Orderのフィールドは以下の5つに分類できます。

• 注文に関するもの
• 顧客に関するもの
• 金額に関するもの
• 商品に関するもの
• 決済に関するもの
• 配送に関するもの
• 返金に関するもの

順番に紹介していきます。

Orderの注文に関する主要なフィールド

注文のキャンセル

注文はいくつかの理由によりキャンセルされる可能性があります。

注文がキャンセルされると、決済や商品の配送は行われません。

また、Orderオブジェクトも削除されます。

キャンセルの理由を表すのがOrderCancelReasonという列挙型であり、以下のいずれかの値を取ります。

• CUSTOMER・・・顧客がキャンセルした
• DECLINED・・・決済が完了しなかった
• FRAUD・・・注文が詐欺だった
• INVENTORY・・・在庫が足りなかった
• OTHER・・・その他の理由

注文がキャンセルされた時に、支払いがマーチャントに支払われていれば、決済状況は返金(Refunded)となり、返金処理が行われます。

そうでなければ、決済状況は無効(Voided)となり、顧客のクレジットカードから該当の支払額が引き落とされなくなります。

注文のアーカイブ

マーチャントは管理画面で、注文のアーカイブが行えます。

アーカイブは、API上では「Orderをcloseする」と表現されます。

アーカイブを行うことで、対応すべき注文だけを選択して管理できるようになります。

注文のアーカイブは、主に、商品の配送後や決済完了後に行われます。

アーカイブを行なっても、Order(注文)は削除されません。

Orderの顧客に関する主要なフィールド

customerJourneySummaryフィールド

customerJourneySummaryフィールドには、顧客が最初にページに訪問して注文するまでの行動に関するデータが含まれます。

顧客が注文までに生成したセッション数や、各セッションで最初に見られたページ、流入元など、有益な情報があります。

disputesフィールド

disputesには顧客からの苦情に関する情報が含まれます。

苦情への対応状況として、調査や、返信待ち、返金といった状態が設定されます。

Orderの金額に関する主要なフィールド

Shopに設定されている通貨と決済通貨が異なる場合は、注文に2種類の通貨単位が関わります。

それを考慮して、金額に関するフィールドにはMoneyBagというオブジェクトが使われます。

MoneyBagは、1つの通貨量を、決済通貨の単位と、Shopに設定された通貨単位の両方で表現します。

これらのフィールドに関して以下の式が成り立ちます。

subTotalPrice = (注文に含まれる商品の価格の合計) – totalDiscountSet

totalPriceSet = subTotalTaxSet + totalShippingPriceSet + totalTaxSet

実際に、注文後に表示される画面は以下のようになります。

商品価格の合計は10,000円となっています。

「V6H0NAZ931J5」は、クーポンコードによるディスカウントです。

この場合、totalDiscountSetは500円です。

「小計」は、subTotalPriceSetフィールドに対応します。

「配送」は、totalShippingPriceSetフィルドに対応します。

「税」は、totalTaxSetフィールドに対応します。

「合計」は、totalPriceSetフィールドに対応します。

上記の注文にGraphQLでクエリーした結果も載せておきますので、参考にしてください！

{
  "data": {
    "order": {
      "taxesIncluded": false,
      "currentTaxLines": [
        {
          "rate": 0.1,
          "ratePercentage": 10
        }
      ],
      "taxLines": [
        {
          "rate": 0.1,
          "ratePercentage": 10
        }
      ],
      "totalTaxSet": {
        "shopMoney": {
          "amount": "1050.0"
        }
      },
      "subtotalPriceSet": {
        "shopMoney": {
          "amount": "9500.0"
        }
      },
      "totalPriceSet": {
        "shopMoney": {
          "amount": "11550.0"
        }
      },
      "totalShippingPriceSet": {
        "shopMoney": {
          "amount": "1000.0"
        }
      },
      "totalDiscountsSet": {
        "shopMoney": {
          "amount": "500.0"
        }
      }
    }
  },
  # 省略
}

Orderの商品に関する主要なフィールド

Orderは注文に含まれる商品の情報をLineItemのConnectionという形で保持します。

LineItemはProductVariant(商品バリエーション)と1対1で結びつき、商品情報と購入数といった情報を持っています。

Orderの決済に関する主要なフィールド

先ほど、「MoneyBagは、1つの通貨量を、決済通貨の単位と、Shopに設定された通貨単位の両方で表現する」と説明しました。

その2つの通貨単位が、ここに出てくる、currencyCodeとpresentmentCurrencyCodeです。

クレジットカード決済では、マーチャントは各クレジットカード会社に顧客のクレジットカードの有効性を検証してもらい、承認(aithorization)を貰います。承認されると、売上がマーチャントに支払われます(capture)。

Orderの配送に関する主要なフィールド

requiresShippingフィールドがfalseの商品例として、音楽や動画、サブスクの会員、といったデジタル商品があります。

shippingLineフィールドには、配送手段や、配送業者などの情報が含まれます。

OrderDisplayFulfillmentStatusは配送状況を列挙型で表現します。主要な値を以下に紹介します。

• FULFILLED・・・発送済み
• IN_PROGRESS・・・発送中
• PARTIALLY_FULFILLED・・・一部発送済み
• UNFULFILLED・・・未発送
• SCHEDULED・・・発送日程をスケジュール済み
• PENDING_FULFILLMENT・・・保留

Orderの返金に関する主要なフィールド

Shopifyでは、顧客が商品を購入した後に、返金を行うことができます。

注文全体や、一部の注文に対する返金が可能です。

商品の返品を伴わない返金も可能です。

返金は、顧客が支払いに使った決済手段を通して行われます。

最後に

今回は、CustomerとOrderを紹介しました。

どちらもShopify APIにおいて中心的な役割を果たします。

特にOrderは、商品や決済、在庫に関するオブジェクトのハブとなっています。

Orderのフィールドは80個以上あり、今回説明し切れなかったものもたくさんあります。

しかし、それらは今回紹介したフィールドの派生として捉えることができます。

例えば、currentTotalPriceSetは、返品が行われない限り、今回紹介したtotalPriceSetと同じ値となります。

返品が行われると、最新のお支払い合計価格を保持するために、currentTotalPriceSetが書き換えられます。

originalTotalPriceSetも同様に、注文編集(OrderEditing)という操作が行われない限りは、totalPriceSetと同じ値をとります。

今回紹介した概念やフィールドを理解した後に、派生的な概念を獲得していくと、情報量の多いリファレンスも読み解けるようになるでしょう。

【Shopify GraphQL API徹底解説】シリーズでは、今回のように密接に関係するオブジェクトをまとめて紹介していきます。

シリーズを通して、主要なオブジェクトと、その関係性を理解すれば、Shopify GraphQL APIの強力さを体感できるはずです。