タグアーカイブ 注文返金

WooCommerce 11.1ベータ版が公開！EU注文撤回と返金APIの全容

WooCommerce 11.1のベータ版が公開された。今回のリリースではEU顧客向けの注文撤回フロー、REST APIの新しい返金計算エンドポイント、バリエーション商品のパフォーマンス改善が柱となる。正式版は2026年9月1日にリリース予定だ。

この記事では開発者向けブログの情報を基に、主要な変更点と実務への影響を解説する。ストア運営者とエクステンション開発者の双方が押さえておくべきポイントをまとめた。

WooCommerce 11.1の全体像

WooCommerce 11.1には大きく4つの改善領域がある。EU消費者保護に対応する注文撤回機能、返金計算を自動化するREST APIエンドポイント、商品CSVのインポートとエクスポートのバグ修正、そしてバリエーション商品の表示速度向上のためのパフォーマンス修正だ。

これらに加え、エクステンション開発者向けの互換性修正も複数含まれる。ブロック登録のスキップによる管理画面の負荷軽減、エディタアセットの統合実験など、開発者向けの変更も見逃せない。なお、この段階ではあくまでベータ版であり、フィードバックが募集されている。

この図はWooCommerce 11.1の4つの柱を示している。それぞれの詳細を順に見ていこう。

EU顧客向けの注文撤回フローが登場

WooCommerce 11.1では、EU消費者保護指令に基づく注文撤回権（right of withdrawal）に対応する機能が追加された。顧客はマイアカウントの専用ページから注文撤回を申請できる。EU圏では消費者が契約後一定期間内に理由なく注文を取り消せる権利が法律で定められている。この機能はその権利をストア運営者がスムーズに扱うための仕組みだ。

顧客が注文撤回を申請すると、ストア運営者にメール通知と管理画面のインボックス通知が届く。加盟店はその通知を確認して返金手続きを進める流れだ。申請時に認証は不要で、顧客は管理画面のワードプレスログインを必要としない。これはEUの消費者保護の原則に沿った設計である。

注文撤回の申請から返金までの流れはこの3ステップで完結する。ストア運営者は通知を確認してから対応すればよいため、顧客とのやり取りを記録しやすい。

この機能はデフォルトでは無効化されている。利用するにはWooCommerceの設定画面から「設定 → 詳細 → 機能」と進み、注文撤回機能を有効化する必要がある。EU圏向けにストアを運営している場合は導入を検討したい。

REST APIの返金エンドポイントが強化された

返金処理を外部システムから操作する開発者にとって大きな変更が入った。WooCommerce REST APIの返金フローが更新され、サーバー側で返金額を自動計算できるようになった。従来は返金額を手動で計算してリクエストに含める必要があったが、その手間を省ける。

既存の返金エンドポイントに compute_totals フィールドが追加された。このフィールドに true を指定すると、WooCommerceサーバーが商品代金、送料、税を自動的に計算して返金額を確定する。計算ミスによる返金誤りを防げるのが利点だ。

POST /wc/v3/orders/123/refunds
{
  "compute_totals": true
}

この例では注文番号123に対して返金リクエストを送信している。ボディに compute_totals を指定するだけで、あとはWooCommerceが注文の明細を基に返金額を算出する。手動で計算する必要がなくなった。

さらに新しいプレビューエンドポイントも追加された。POST /wc/v3/orders/123/refunds/preview を使うと、実際に返金を実行せずに計算結果だけを確認できる。返金額を事前に検証したいケースや、顧客に返金額を提示する前に確認したいケースで重宝する。

POST /wc/v3/orders/123/refunds/preview

このプレビューエンドポイントは、返金処理を自動化するシステムを構築する際にデバッグと金額確認を容易にする。実際に返金を実行せずに結果を確認できるため、開発環境でのテストにも適している。

この比較が示すように、返金処理の負担が大きく軽減された。外部システムから返金を自動化する際の堅牢性も向上している。

Store APIのチェックアウト金額チェック

Store APIにも改善が入った。チェックアウトエンドポイントに expected_total というオプションフィールドが追加された。このフィールドには顧客が画面上で確認した合計金額を整数で指定する。サーバー側で計算した金額と一致しない場合、リクエストは失敗し、新しい 409 エラーレスポンスが返される。

このエラーレスポンスのコードは woocommerce_rest_checkout_total_mismatch で、金額の不一致が発生したことをシステムが判別できる。顧客が画面で見た金額と実際に請求される金額が食い違う事故を未然に防ぐための仕組みだ。

この仕組みはチェックアウトの金額改ざんや画面表示の不整合を検出するために有効だ。決済処理を独自に実装している場合は特に注目したい。

バリエーション商品のパフォーマンス改善

バリエーション商品を多数抱えるストアでは、商品編集画面や店舗フロントの表示が遅くなる問題があった。WooCommerce 11.1ではこの問題に対処する複数のパフォーマンス修正が含まれている。主な改善は、バリエーションと属性の読み込み時に発生するN+1クエリの削減だ。

N+1クエリとは、1つの親データを取得した後、子データを1件ずつ追加で取得してしまう非効率なデータベースアクセスのことだ。たとえば100件のバリエーションがあると、101回のクエリが実行される。修正後は必要なデータをまとめて取得するため、クエリ回数が大幅に減る。

加えて価格キャッシュの処理も改善された。変動価格商品の価格計算ではキャッシュを活用してクエリを削減している。管理画面とフロントエンドの両方で、商品数の多いストアほど体感できる差が生まれるはずだ。

ブロック登録の条件付きスキップ

WooCommerce 11.1では、ブロックタイプとパターンの登録処理が見直された。従来はほぼすべてのリクエストでブロックが登録されていたが、新しい BlockRegistrationContext ガードを導入し、cron、AJAX、REST APIリクエストでは登録をスキップするようになった。

フロントエンド、管理画面、エディタの動作は従来通り維持される。つまり、実際にブロックを描画または編集する場面でのみ登録が走り、不要な場面では処理を省く。これにより管理画面のバックエンド処理が軽くなる。

1つ例外がある。商品やバリエーションの説明文にWooCommerceブロックが含まれている場合、woocommerce_short_description フィルターを通じて必要に応じてブロックタイプが登録される。商品REST API、Store API、バリエーションAJAXエンドポイント、商品ウェブフックでも説明文が正しく描画される。

エクステンション開発者への影響もある。すべてのリクエストでブロック登録が走ることを前提にした実装は修正が必要になる。新しい woocommerce_should_register_blocks フィルターで、スキップされたコンテキストでもブロックを登録するようにオプトインできる。

メールエディタの更新

ブロックベースのメールエディタにも機能追加があった。core/embed ブロックが、クリック可能なサムネイルを描画するプロバイダーで挿入できるようになった。対象はYouTube、Vimeo、VideoPress、TikTok、Dailymotion、そしてWordPressの埋め込みだ。WordPressの埋め込みはリッチなリンクカードとして表示される。

オーディオプロバイダーは対象外だ。また、未対応のプロバイダーからの埋め込みは貼り付けることはできるが、エディタが警告を表示し、配信時にはリンクとして送信される。メールに動画サムネイルを入れたい場合は、対応プロバイダーのURLを使うとよい。

パーソナライゼーションタグのコールバックにも改善が入った。タグが送信先のコンテンツタイプを受け取れるようになり、HTML、プレーンテキスト、href 属性のそれぞれに適切にエスケープできるようになった。新しいパラメータはオプションで、デフォルトはHTMLだ。自動エスケープは新しく登録されたテキスト型タグにのみ適用される。

実験的機能のプレビュー

WooCommerce 11.1には2つの実験的機能が含まれている。1つは統合ブロックエディタアセットだ。ブロックごとに個別のスクリプトとスタイルを読み込む代わりに、共有のJavaScriptとCSSバンドルに置き換える仕組みである。

テストによると、エディタのアセット数が91.7%削減され、ネットワーク転送サイズが48.3%減少、スタイルバンドルは62.3%小さくなった。フロントエンドのアセットには変更がない。デフォルトでは無効で、WooCommerceの設定画面から「詳細 → 機能 → 実験的機能」と進んで有効化できる。

この実験的機能が正式採用されれば、ブロックエディタの読み込み速度が大きく改善される。開発段階の指標ではあるが、かなり有望な結果だ。

もう1つの実験的機能は商品ギャラリービデオの内部ストレージだ。商品ギャラリーに動画を追加する第一歩として、動画データを保存する内部構造がフラグの後ろに実装された。設定画面から「商品ギャラリービデオ（ベータ）」を有効化すると使える。

開発者向けの互換性注意事項

WooCommerce 11.1では開発者が把握しておくべき互換性修正が複数含まれている。is_rest_api_request() 関数は、これまで /wp-json/ のパーマリンクパスのみでRESTリクエストを検出していた。今回の修正で、空でない rest_route クエリパラメータもRESTリクエストとして扱うようになった。クエリ形式のRESTルートを使う実装では挙動が変わる可能性がある。

• ProductGalleryUtils::get_product_gallery_image_count() は非推奨となり、get_product_gallery_media_count() に置き換えられた。旧メソッドは非推奨通知を出すシムとして復元されている
• 数量ステッパーのDOM順序が視覚的な順序と一致するように修正された。旧DOM順序に依存するCSSを書いているテーマは再テストが必要だ
• WC_Order_Item_Product::set_product() は variation_id をリセットするようになった。部分的なREST注文更新では product_id が変わらない場合、variation_id が保持される
• search_products() はORグループの結合を括弧で囲むようになった。これにより include、exclude、status、type の条件が全グループに適用される。結果セットが変わる
• 新しい GET /wc-analytics/activity-panel/counts エンドポイントが3つの従来エンドポイントを統合し、管理画面のページ読み込みあたり6回のリクエストを1回に削減する
• アナリティクスページの出力からリクエスト由来のプロパティが除去された。キャッシュされたページが別の訪問者のリクエストデータを漏洩する事故を防ぐ
• @woocommerce/entities は window.wc.wcEntities で内部ユーティリティを公開しなくなった。これらはもともと公開APIではない
• 通貨記号の出力がMOP（P から MOP$）とZMW（ZK から K）で変更された。既存の記号オーバーライドフィルターは引き続き動作する

この記事のポイント

• WooCommerce 11.1ベータ版は2026年9月1日に正式リリース予定
• EU顧客向けの注文撤回フローが追加され、デフォルトでは無効
• REST APIに返金自動計算とプレビューエンドポイントが登場
• Store APIの expected_total によりチェックアウト時の金額不一致を検出
• バリエーション商品のN+1クエリ削減で管理画面とフロントの表示が高速化

海田 洋祐

・ 複数業界における17年間のデジタルビジネス開発経験
・ ウェブサイト開発のためのHTML、PHP、CSS、JavaScript等の実用的知識
・ 15ヶ国語対応の多言語SaaSの開発経験
・ 17年間にも及ぶ、Eコマース長期運営経験
・ 幅広い業界でのSEO最適化の豊富な経験

www.aandgweb.co.jp