【Shopify GraphQL API徹底解説】商品の配送に関わる4つのオブジェクト
この記事の所要時間： 8分
Graph APIは最初から全てを理解することが困難なので、範囲を決めて少しずつ理解していく必要があります。
【Shopify GraphQL API徹底解説】シリーズでは、Shopify GraphQL APIの仕様から、主要なオブジェクトを少しずつ読み解いていきます。
説明は記事内で完結しているので、シリーズの他の記事を参照しなくても理解できるようにしています。
今回解説するのは以下の4つのオブジェクトです。
- Fulfillment
- LineItem
- FulfillmentLineItem
- FulfillmentOrder
Fulfillment関連オブジェクトの関係性
注文(Order)が作成されると、それに対応する複数の配送(Fulfillment)が作成されます。
注文(Order)には複数の商品バリエーションが含まれることがあり、それぞれはLineItemで表現されます。
LineItemに、その配送に関する情報を提供するのがFulfillmentItemです。
一方、FulfillmentOrderは、同じ場所から同じタイミングで発送される商品のまとまりです。
FulfillmentOrderは、複数のFulfillmentItemとむすび付いています。
配送に関するオブジェクトは複雑に絡み合っているので、一度に理解するのは難しいかもしれません。
それぞれのオブジェクトの詳細を見ていくことで、全体的なイメージを作っていきましょう。
Fulfillment
Fulfillmentは、顧客からの注文に含まれる商品の配送を表現します。
１つの注文に複数のFulfillmentが含まれることがあります。
Fulfillmentの主要なフィールド
| name | String! | fulfillmentの名称 |
| order | Order! | fulfillmentが属する注文(Order) |
| totalQuantity | Int! | fulfillmentに含まれるLineItemの合計 |
| status | FulfillmentStatus! | fulfillmentの状態 |
| displayStatus | FulfillmentDisplayStatus | 表示されるfulfillmentの状態 |
| location | Location | 配送元の場所。倉庫の場所など。 |
| service | FulfillmentService | ストアオーナーからfulfillmentを請け負う配送業者 |
| trackingInfo (引数としてfirstを受け取り、指定された長さで配列を切り捨てる。) | [FulfillmentTrackingInfo! ] ! | fulfillmentの追跡情報のリスト |
| isTransitAt | DateTime | fulfillmentが実際に配送された日時 |
| estimateDeliveryAt | DateTime | 商品が顧客に届く日時 |
totalQuantityフィールド
totalQuantityフィールドにはLineItemの合計が入ります。
LineItemは注文(Order)を構成するオブジェクトです。
注文に含まれる商品バリエーションごとにカート内にLineItemが作られます。
LineItemのフィールドには、商品バリエーションはもちろん、その商品バリエーションの注文数やディスカウント情報が含まれます。
まとめると、totalQuantityは商品バリエーションごとの注文数を足した数ということです。
statusフィールドとdisplayStatusフィールド
statusフィールドは、fulfillmentの状態を表すFulfillmentStatus型の値が入ります。
FulfillmentStatusは列挙型で、以下のいずれかの値を取ります。
- PENDING・・・配送業者が配送リクエストを受理するのを待っている
- OPEN・・・配送業者が配送リクエストを受理した
- SUCCESS・・・配送が完了した
- ERROR・・・配送リクエストでエラーが起きた
- FAILURE・・・配送リクエストが失敗した
- CANCELLED・・・配送がキャンセルされた
displayStatusフィールドは更に細かい状態をマーチャントに表示するために使われます。
主に配送業者によって更新されます。
trackingInfoフィールド
trackingInfoには、配送の追跡情報(FulfillmentTrackingInfo)がリストとして含まれます。
そして、FulfillmentTrackingInfoには以下のフィールドが含まれます。
| company | String | 配送業者の会社名 |
| number | String | 追跡コード |
| url | URL | 追跡情報が見れるページのURL |
LineItem
顧客(Customer)は商品を購入するときに、注文(Order)を作成します。
注文(Order)には、当然、複数の商品バリエーション(ProductVariant)が含まれることがあります。
注文(Order)と商品バリエーション(ProductVariant)をつなぐのが、LineItemです。
注文(Order)は、Connectionで、複数のLineItemとひも付いています。
LineItemは商品バリエーション(ProductVariant)と1対1でむすび付いていて、注文数やディスカウント情報も含んでいます。
LineItemの主要なフィールド
| variant | ProductVariant | このLineItemとひも付いた商品バリエーション |
| quantity | Int! | 商品バリエーションの注文数 |
| originalUnitPriceSet | MoneyBag! | ディスカウントされる前の商品バリエーションの単価 |
| discountAllocations | [DiscountAllocation! ] ! | このLineItemに適用されるディスカウントのリスト |
| discountedTotalSet | MoneyBag! | ディスカウント後の合計価格 |
| sku | String | 商品バリエーションのSKUコード |
FulfillmentOrder
FulfillmentOrderは、注文(Order)に含まれるLineItemのうち、同じ場所から配送されるLineItemをまとめたものです。
同じ場所から配送されるLineItemのリストがあっても、配送されるタイミングが違えば、複数のFulfillmentOrderに分割されます。
簡単に言うと、まとめて配送されるLineItemをグループ化して、配送に関する情報を付け足したオブジェクトです。
FulfillmentOrderの主なフィールド
| order | Order! | fulfillmentOrderにひも付いた注文(Order) |
| assignedLocation | FulfillmentOrderAssignedLocation! | fulfillmentOrderを配送する場所。住所や郵便番号、電話番号が含まれる。 |
| deliveryMethod | DeliveryMethod | fulfillmentOrderの配送手段 |
| destination | FulfillmentOrderDestination | 配送先。住所や郵便番号、電話番号が含まれる。 |
| fulfilledAt | DateTime | 配送される日時 |
| status | FulfillmentOrderStatus! | fulfillmentOrderの状態 |
| requestStatus | FulfillmentOrderRequestStatus! | fulfillmentOrderへの要求に関する状態 |
| supportedActions | [FulfillmentOrderSupportedAction! ] ! | fulfillmentOrderに対して実行できる操作 |
deliveryMethodフィールド
deliveryMethodには、配送手段を表現するDeliveryMethodオブジェクトが入ります。
DeliveryMethodはDeliveryMethodTypeという列挙型のフィールドを持っていて、配送手段を指定します。
DeliveryMethodTypeが取りうる値は以下の5つです。
- LOCAL・・・マーチャントが雇っている配送ドライバーや、マーチャントの従業員が顧客の玄関先まで届ける。
- NONE・・・配送手段なし。手渡しなど。
- PICK_UP・・・顧客が特定の場所に取りに行く。
- RETAIL・・・販売店で購入され、そのまま手渡しされる。Shopify POSを使っている場合が多い。
- SHIPPING・・・配送業者などが配送する。
statusフィールド
statusフィールドが取りうる値は以下の6つです。
- OPEN・・・配送が作成された
- SCHEDULED・・・配送日時が設定され、配送が手配された
- INCOMPLETE・・・配送が要求通りに完了していない
- IN_PROGRESS・・・配送中
- CLOSED・・・配送が完了した
- CANCELLED・・・マーチャントによって配送がキャンセルされた
supportedActionsフィールド
supportedActionsフィールドにはfulfillmentOrderに対して実行できる操作をリストとして設定できます。
操作はFulfillmentOrderActionという列挙型で定義されていて、配送のキャンセルや、FulfillmentOrderを別の場所に移動させる、といった操作があります。
FulfillmentLineItem
FulfillmentLineItemは、特定のLineItemに配送に関する情報を付け加えるためのオブジェクトです。
１つのLineItemオブジェクトとむすび付いていて、配送する商品バリエーションの数や、ディスカウント情報を含みます。
FulfillmentLineItemの主要なフィールド
| lineItem | LineItem! | ひも付けられたLineItem。商品バリエーションと、注文数の情報。 |
| quantity | Int | 注文数 |
| originalTotalSet | MoneyBag! | ディスカウントが適用される前の合計価格 |
| discountedTotalSet | MoneyBag! | ディスカウント適用後の合計価格 |
最後に
今回は、配送に関わる4つのオブジェクトを解説しました。
配送方法にはいくつかのオプションがありました。
RETAILを設定すれば、販売店のPOSから作成された注文を管理することができます。
LOCALを設定すれば、マーチャントが配達ドライバーを抱えるケースにうまく対応することができます。
顧客が特定の場所に商品を取りに行く、PICK_UPというオプションもあります。
オンラインショップに求められる配送方法や、カスタマイズは多岐に渡ります。
Shopifyの配送に関わるAPIは、それらに対応するべく、柔軟性が高く設計されています。
その反面、オブジェクト同士が複雑に絡み合っており、理解を難しくしています。
今回の内容に対する理解を深めるために、配送業務について学習することをおすすめします。
- 顧客はどのような配送オプションを求めているのか？
- 商品を受け取る場所や時間をどのようにコントロールするべきなのか？
- 注文された商品を、どの倉庫から配送すべきなのか？
- 配送状況をどのように把握して、顧客やマーチャントに伝えるべきなのか？
このような問いに対して、各種配送サービスが出している答えがあります。
それを調べると、Shopfiy APIの設計が納得できるかもしれません。
是非、粘り強い学習の果てに、すばらしいアプリを開発してください！
【Shopify GraphQL API徹底解説】シリーズでは、今回のように密接に関係するオブジェクトをまとめて紹介していきます。
シリーズを通して、主要なオブジェクトと、その関係性を理解すれば、Shopify GraphQL APIの強力さを体感できるはずです。
