🧑‍💻

【Shopify.dev和訳】Ajax API/Reference/Product recommendations

2021/09/12に公開

API

Shopify

Ajax

tech

この記事について

この記事は、Product Recommendations API referenceの記事を和訳したものです。

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

Shopify アプリのご紹介

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

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

Product Recommendations API reference

Product Recommendations API を使用すると、指定された製品の関連製品を推奨することができます。おすすめの作成方法や関連する制限事項については、「製品のおすすめ」を参照してください。

テーマでおすすめ商品を表示する方法については、「おすすめ商品を表示する」を参照してください。

GET /recommendations/products.json

次のリクエスト例では、特定の製品の推奨製品を取得しています。

GET /recommendations/products.json?product_id={product-id}

クエリパラメーター

Query parameter	Required	Description
`product_id`	Yes	おすすめ商品を表示したい商品の一意の商品 ID。
`limit`	No	結果の数を制限します。値の範囲は `1` ~ `10` で、デフォルトは `10` です。

Example request object

{
  "product_id": "1234567890123",
  "limit": 4
}

Example request using Fetch

fetch("/recommendations/products.json?product_id=1234567890123&limit=4")
  .then(response => response.json())
  .then(({ products }) => {
    if (products.length > 0) {
      const firstRecommendedProduct = products[0];

      alert(
        `The title of the first recommended product is: ${firstRecommendedProduct.title}`
      );
    }
  }
);

Products response

以下の例は、/recommendations/products.json エンドポイントへのリクエストが成功した場合のレスポンスです。

Example product response

{
 "products": [
   {
     "id": 35,
     "title": "Gorgeous Silk Coat",
     "handle": "gorgeous-silk-coat",
     "description": null,
     "published_at": "2019-02-26T11:34:58-05:00",
     "created_at": "2019-02-26T11:34:58-05:00",
     "vendor": "Marge Group",
     "type": "Outdoors",
     "tags": [],
     "price": 380000,
     "price_min": 380000,
     "price_max": 790000,
     "available": true,
     "price_varies": true,
     "compare_at_price": null,
     "compare_at_price_min": 0,
     "compare_at_price_max": 0,
     "compare_at_price_varies": false,
     "variants": [
       {
         "id": 69,
         "title": "Small Aluminum Knife",
         "option1": "Small Aluminum Knife",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Silk Coat - Small Aluminum Knife",
         "public_title": "Small Aluminum Knife",
         "options": [
           "Small Aluminum Knife"
         ],
         "price": 790000,
         "weight": 9500,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       },
       {
         "id": 70,
         "title": "Heavy Duty Bronze Shoes",
         "option1": "Heavy Duty Bronze Shoes",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Silk Coat - Heavy Duty Bronze Shoes",
         "public_title": "Heavy Duty Bronze Shoes",
         "options": [
           "Heavy Duty Bronze Shoes"
         ],
         "price": 380000,
         "weight": 2200,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       }
     ],
     "images": [],
     "featured_image": null,
     "options": [
       {
         "name": "Color or something",
         "position": 1,
         "values": [
           "Small Aluminum Knife",
           "Heavy Duty Bronze Shoes"
         ]
       }
     ],
     "url": "/products/gorgeous-silk-coat?pr_choice=default&pr_prod_strat=copurchase&pr_rec_pid=35&pr_ref_pid=17&pr_seq=alternating"
   },
   {
     "id": 13,
     "title": "Gorgeous Wooden Computer",
     "handle": "gorgeous-wooden-computer",
     "description": null,
     "published_at": "2019-02-26T11:34:15-05:00",
     "created_at": "2019-02-26T11:34:15-05:00",
     "vendor": "Purdy Inc",
     "type": "Garden",
     "tags": [],
     "price": 930000,
     "price_min": 930000,
     "price_max": 1730000,
     "available": true,
     "price_varies": true,
     "compare_at_price": null,
     "compare_at_price_min": 0,
     "compare_at_price_max": 0,
     "compare_at_price_varies": false,
     "variants": [
       {
         "id": 25,
         "title": "Mediocre Silk Bottle",
         "option1": "Mediocre Silk Bottle",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Wooden Computer - Mediocre Silk Bottle",
         "public_title": "Mediocre Silk Bottle",
         "options": [
           "Mediocre Silk Bottle"
         ],
         "price": 1730000,
         "weight": 5700,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       },
       {
         "id": 26,
         "title": "Lightweight Paper Shirt",
         "option1": "Lightweight Paper Shirt",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Wooden Computer - Lightweight Paper Shirt",
         "public_title": "Lightweight Paper Shirt",
         "options": [
           "Lightweight Paper Shirt"
         ],
         "price": 930000,
         "weight": 6600,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       }
     ],
     "images": [],
     "featured_image": null,
     "options": [
       {
         "name": "Color or something",
         "position": 1,
         "values": [
           "Mediocre Silk Bottle",
           "Lightweight Paper Shirt"
         ]
       }
     ],
     "url": "/products/gorgeous-wooden-computer?pr_choice=default&pr_prod_strat=description&pr_rec_pid=13&pr_ref_pid=17&pr_seq=alternating"
   }
 ]
}

Error responses

/recommendations/products.json エンドポイントへのリクエストに失敗した場合は、以下のいずれかのエラーレスポンスが返されます。

Invalid parameter

product_id パラメータがない場合、エンドポイントは以下のエラーを返します。

{
  "status": 422,
  "message": "Invalid parameter error",
  "description": "A product_id value is missing"
}

Product not found

product_id が存在しない製品、またはオンラインストアチャネルで公開されていない製品の場合、エンドポイントは次のエラーを返します。

{
  "status": 404,
  "message": "Product not found",
  "description": "No product with id <product_id> is published in the online store"
}

GET /recommendations/products

次のリクエスト例では、特定の製品に対する製品推奨事項を表示したセクションの HTML を取得しています。

GET /recommendations/products?product_id={product-id}&section_id=product-recommendations

クエリパラメーター

Query parameter	Required	Description
`product_id`	Yes	おすすめ商品を表示したい商品の一意の商品 ID。
`limit`	No	結果の数を制限します。値の範囲は `1` ~ `10` で、デフォルトは `10` です。
`section_id`	Yes	製品の推奨事項とともにレンダリングするセクションファイルの一意のセクション ID。

Example request object

{
  "product_id": "1234567890123",
  "limit": 4,
  "section_id": "product-recommendations"
}

Example request using Fetch

const productRecommendationsSection = document.querySelector('.product-recommendations');

fetch("/recommendations/products?product_id=12345690123&limit=4&section_id=product-recommendations")
 .then(response => response.text())
 .then((text) => {
    const html = document.createElement('div');
    html.innerHTML = text;
    const recommendations = html.querySelector('.product-recommendations');

    if (recommendations && recommendations.innerHTML.trim().length) {
      productRecommendationsSection.innerHTML = recommendations.innerHTML;
    }
 });

Section response

/recommendations/products エンドポイントへのリクエストが成功したときのレスポンスです。

セクションレスポンスには、指定されたセクションの HTML が、指定された製品に対する推奨製品を含む recommendations オブジェクトとともにレンダリングされています。

例えば、以下のセクションでは、以下のセクション・レスポンスが生成されます。

Example section

{%- if recommendations.performed -%}
  <div id="product-recommendations">
    {%- if recommendations.products_count > 0 -%}
      <h2>You may also like</h2>

      <ul>
        {%- for product in recommendations.products -%}
          <li class="grid__item small--one-half medium-up--one-quarter">
            <a href="{{ product.url }}">
              <span>{{ product.title }}</span>
              <span>{{ product.price | money }}</span>
            </a>
          </li>
        {%- endfor -%}
      </ul>
    {%- endif -%}
  </div>
{%- endif -%}

Example section response

<div id="product-recommendations">
  <h2>You may also like</h2>

  <ul>
    <li class="grid__item small--one-half medium-up--one-quarter">
      <a href="/products/gorgeous-silk-coat?pr_choice=default&pr_prod_strat=copurchase&pr_rec_pid=35&pr_ref_pid=17&pr_seq=alternating">
        <span>Gorgeous Silk Coat</span>
        <span>$380.00</span>
      </a>
    </li>
    ...
  </ul>
</div>

Error responses

/recommendations/products エンドポイントへのリクエストに失敗した場合は、以下のエラーステータスコードのいずれかが返されます。

Status code	Description
`404`	・Product not found - 指定されたプロダクト ID が存在しないか、オンラインストアチャンネルで公開されている商品に属していません。・Section not found - 指定されたセクション ID は、テーマ内で見つかりませんでした。
`422`	Invalid parameter error - `product_id` のクエリパラメータがありませんでした。

製品の推奨事項のコンバージョンの追跡

products response の各 product の url プロパティには、コンバージョンファネルを構築するための URL パラメータが含まれており、Shopify のレポートを使用して追跡することができます。同様に、recommendation.products に返されるリキッドの url プロパティにも、このトラッキング情報が含まれています。

商品推奨レポートについての詳細は、Product recommendation conversion over time をご覧ください。

Shopify アプリのご紹介

Discussion

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