Zenn
🗞

【Shopify.dev和訳】Apps/Subscriptions/Orders

2021/09/17に公開
Shopify
#
apps
tech

この記事について

この記事は、Apps/Subscriptions/Ordersの記事を和訳したものです。

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

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

プリペイドサブスクリプションの注文を管理する

Shopify によって注文が作成され、配送アンカーが存在する場合、注文には前払い商品の遅延履行注文が含まれます。このチュートリアルでは、フルフィルメント注文とサブスクリプション契約に関連するいくつかの一般的な注文管理シナリオについて説明します。

注文とサブスクリプション契約の同期を維持する

プリペイドサブスクリプション契約への変更は、関連する注文に自動的に反映されません。たとえば、顧客がアプリでプリペイドサブスクリプションの住所を更新しても、注文の住所は自動的に更新されません。このユースケースをサポートするには、SubscriptionContractUpdate とsubscriptionDraftUpdate を呼び出して、コントラクトの配信方法アドレスを更新する必要があります。また、OrderUpdateを呼び出して、注文の配送先住所を更新する必要があります。

Fulfillment orders and subscription contracts app workflow

サブスクリプション契約の更新

サブスクリプションドラフトを更新する前に、ドラフト ID を取得する必要があります。

subscriptionContractUpdateミューテーションを使用して、サブスクリプションコントラクト ID を指定します。応答にはドラフト ID が含まれます。

Example request
POST /admin/api/2021-01/graphql.json

mutation {
  subscriptionContractUpdate(contractId: "gid://shopify/SubscriptionContract/22") {
    draft {
      id
    }
    userErrors {
      field
      message
    }
  }
}

JSON response

{
  "data": {
    "subscriptionContractUpdate": {
      "draft": {
        "id": "gid://shopify/SubscriptionContract/22"
      },
      "userErrors": []
    }
  },
  ...
}

サブスクリプションドラフトの更新

subscriptionDraftUpdateミューテーションを呼び出して、サブスクリプションドラフトに変更を加えることができます。次の例では、配信方法のアドレスが変更されています。

Example request
POST /admin/api/2021-01/graphql.json

mutation subscriptionDraftUpdate($draftId: ID!, $input: SubscriptionDraftInput!) {
  subscriptionDraftUpdate(draftId: $draftId, input: $input) {
    draft {
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}

Input

{
  "draftId": "gid://shopify/SubscriptionDraft/2654264",
  "input": {"deliveryMethod": {
    "shippingAddress": {
      "address1": "123 Fake Street",
      "city": "Vancouver",
      "countryCode": "CA",
      "provinceCode": "BC",
      "zip": "V6Z0A3",
      "lastName": "Doe"
                }
      }
    }
  }
}

JSON response

{
  "data": {
    "subscriptionDraftUpdate": {
      "draft": {
        "id": "gid://shopify/SubscriptionDraft/2654264"
      },
      "userErrors": []
    }
  },
  ...
}

注文の更新

OrderUpdateミューテーションを呼び出して、注文を変更できます。次の例では、注文を更新して配送先住所を含めます。

Example request

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

mutation orderUpdate($input: OrderInput!) {
  orderUpdate(input: $input) {
    order {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Input

{
  "input": {
    "id": "gid://shopify/Order/2067697074232",
    "shippingAddress": {
      "address1": "123 Fake Street",
      "city": "Vancouver",
      "countryCode": "CA",
      "provinceCode": "BC",
      "zip": "V6Z0A3",
      "lastName": "Doe"
    }
  }
}

JSON response

{
  "data": {
    "orderUpdate": {
      "order": {
        "id": "gid://shopify/Order/2067697074232"
      },
      "userErrors": []
    }
  },
  ...
}

キャンセルの管理

サブスクリプション契約に関連する注文をキャンセルしても、これらのサブスクリプション契約は自動的にキャンセルされません。サブスクリプション契約の注文がキャンセルされたときにアプリがorders/cancelWebhook をサブスクライブし、マーチャントと通信することをお勧めします。これにより、マーチャントはサブスクリプション契約もキャンセルされていないことを知ることができます。

カスタマーポータルを介したサブスクリプションのキャンセル

顧客がカスタマーポータルを介してサブスクリプション注文をキャンセルする場合、アプリはこのキャンセルを販売者に通知する必要があります。キャンセルがアプリを通じて開始された場合、アプリは関連する返金を処理する必要があります。これは、プリペイドサブスクリプションとサブスクライブアンドセーブサブスクリプションの両方に適用されます。

タグ付けを注文する

マーチャントは、Shopify 管理者でサブスクリプション注文を識別してフィルタリングすることがよくあります。アプリからのサブスクリプションの注文にタグを付けるには、REST で/ ordersエンドポイントを使用するか、GraphQLOrder ミューテーションを送信します。次の例では、注文 ID を使用して特定の注文にタグを追加します。

REST

PUT
https://{shop}.myshopify.com/admin/api/2021-07/orders/{order_id}.json

{
  "order": {
    "id": "2067697074232",
    "tags": "subscription, prepaid"
  }
}

API response

{
    "order": {
        ...
        "tags": "prepaid, subscription",
        ...
            }
}
GraphQL
mutation tagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Input

{
  "id": "gid://shopify/Order/2067697074232",
  "tags": ["subscription", "prepaid"]
}

JSON response

{
  "data": {
    "orderUpdate": {
      "order": {
        "id": "gid://shopify/Order/2067697074232"
      },
      "userErrors": []
    }
  },
  ...
}

:::

自動フルフィルメント

スケジュールされたフルフィルメント注文は、自動フルフィルメントの対象にはなりません。ただし、最初のフルフィルメントオーダーがOPEN状態に設定された状態でプリペイドサブスクリプションオーダーが作成された場合、フルフィルメントオーダーは自動的にフルフィルメントされます。

販売計画の締め切り日の設定の例では、顧客は 1 月 8 日に、アンカー前の動作がASAPに設定されている販売計画のアイテムをチェックアウトします。その後、最初の履行注文（1 月 8 日のfulfillAt日付）がすぐに履行されます。

CSV エクスポートを注文する

CSV エクスポートを使用してフルフィルメントを管理するアプリは、lineItem.fulfillableQuantityの値に依存して、フルフィルメントの準備ができている注文を判別できます。これは、SCHEDULEDフルフィルメント注文が注文lineItem.fulfillableQuantityの計算に含まれていないためです。

たとえば、1 月 15 日に出荷される予定のフルフィルメント注文について考えてみます。1 月 15 日より前は、lineItem.fulfillableQuantityが 0 に設定されています。1 月 15 日以降、lineItem.fulfillableQuantityは 1 に設定されます。次に、アイテムが実行された後、lineItem.fulfillableQuantityは 0 に戻されます。

Webhook を注文する

次の Webhook は、マーチャントのフルフィルメント注文を管理するアプリに役立ちます。

  • orders/create-注文が作成されたときに通知を受け取ります。アプリは、ラインアイテムとその販売プランアプリケーションをチェックして、これが自分が所有するサブスクリプション注文であるかどうかを判断する必要があります。
  • orders/updated-サブスクリプション契約のある注文が更新されたとき、またはスケジュールされたフルフィルメント注文がOPEN状態に移行したときに通知を受け取ります。たとえば、これは住所の更新にとって重要である可能性があります。
  • orders/cancelled-注文がキャンセルされたときに通知を受け取ります。これは、アプリが契約を確実にキャンセルするのに役立ちます（それがマーチャントの意図である場合）。
  • refunds/create-払い戻しが作成されたときに通知を受け取ります。これは、アプリが契約も更新されるようにするために役立ちます（それがマーチャントの意図である場合）。

次のステップ

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

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