This page announces additions and changes to the API (Keep a Changelog format).
You can check the current API version via the X-API-Version response header.
Paths under /v1 maintain backward compatibility (we do not make changes that break existing integrations.
If an incompatible change ever becomes unavoidable, we will provide a new path in parallel and announce it here with an ample migration period).
portal_cart_url, a link that opens the same cart in the buyer portal, to the responses of the MCP cart tools
(get_cart / add_to_cart / update_cart_item / remove_cart_item / set_cart_ship_to). You can review a cart built by AI in the portal
and place the order as is (cards can also be registered in the portal). REST API responses are unchangedstock_observed_at now returns the latest time the stock was confirmed (the later of when it was last checked and when the quantity last changed)expected_arrival as null, and preorders for them (POST /v1/preorders and quote)
return 422 PREORDER_ARRIVAL_UNDETERMINED. has_preorder and preorder=only|exclude now consider only variations that are open for preorderGET /v1/products?q=, MCP search_products)q is given, results are now sorted by relevance (exact brand / model-number match > phrase in the product name > each word in the product name >
other matches; ties by last update, newest first). Pass sort=updated for the previous order. Without q, the order is unchangedq=4901234567894,4909876543214). Variation JANs are matched as beforeq consisting of a single alphanumeric character returns 400 INVALID_QUERY (a single kanji or kana character still works)towel or Handtuch finds towelsbuyer_price) of eligible products is the
discounted price and orders are placed at that price (the order breakdown, invoice format and retail_price are unchanged)campaign (code / label / rate_pct / ends_at); null when no campaign is runninglist_price (regular wholesale price) and list items carry min_list_price / max_list_price.
Always present; higher than buyer_price while a campaign applies and equal otherwise (not used in any total)PRICE_CHANGED (fetch the cart again before ordering)?format=jpeg to return the full-size image as JPEG (cannot be combined with ?w=240|800; omitting it keeps the
previous behavior). Use it for import targets that do not accept WebPship_to.postal_code on orders, PUT /v1/cart/ship-to, and ship_to_postal_code on the preorder quote) are now
validated as 7 digits (hyphen optional, full-width digits accepted) and stored / returned normalized as 150-0001. Values that are not
7 digits return 400 (previously any non-empty value was accepted). Integrations sending them without a hyphen or in full-width keep
working (only the stored form is unified)ship_to.tax_id: { type, value } (used for overseas orders).
Whether the destination country requires one, and which types are accepted, is available as tax_id_requirement in
GET /v1/cross-border/eligibility (MCP place_order / place_preorder / check_cross_border_eligibility have the same fields)tax_exempt (whether the order is export tax-exempt) to each order in the order list (GET /v1/orders)ship_to.country; domestic orders are unchanged.
Overseas orders are tax-exempt (0% consumption tax, tax_exempt: true), international shipping is shown as an estimate before you order
and billed at cost when shipped, and import duties and customs fees are payable by the recipient (DAP). Only part of the catalog is
available for overseas destinations (expanding over time)GET /v1/cross-border/eligibility (per product) /
GET /v1/cross-border/cart-estimate (whole cart). MCP has the same tools (check_cross_border_eligibility / estimate_cross_border_shipping)dest (destination country) to product search, detail, delivery groups and categories, and PUT /v1/cart/ship-to for the cart.
Only products that can ship to the destination are handled (defaults to your registered primary ship-to country;
the MCP search tools accept the same dest, and the cart has set_cart_ship_to)notices to order responses: for overseas orders, who pays duties and which customs documents may be needed
(empty for domestic orders; code is stable, message may change)orderable (whether the product can be ordered), language (language of the product text, ISO 639-1), and ship_from_country (country the product ships from, ISO 3166-1 alpha-2).
Going forward, products shipped from outside Japan or priced in non-JPY currencies may appear as display-only (orderable: false).
At the moment all existing products are orderable: true with language / ship_from_country = null (= Japanese / Japan)currency (price currency, ISO 4217; "JPY" for existing products) and made_to_orderdisplay_name (seller name, only for sellers who disclose it; null for anonymous delivery groups)currency parameter to product search (ISO 4217, default JPY).
min_price / max_price and price aggregates (min_buyer_price etc.) operate within the scope of the specified currency
(no cross-currency price comparison or FX conversion is provided)orderable: false now return 422 NOT_ORDERABLE on cart addition and order placement (no products currently fall into this)POST /v1/preorders/quote (quote, repeatable) → POST /v1/preorders (create).
One preorder covers a single product (multiple variations allowed) and does not use the cart.
Creation performs card authorization only; the actual charge happens when the preorder is confirmedpreorder=include|exclude|only parameter and the has_preorder fieldstock_level gains preorder, and expected_arrival (expected arrival date) is returnedGET /v1/orders?kind=preorder|standard. Orders carry order_kind and expected_arrivalquote_preorder / place_preorder / list_orders toolsX-API-Version header. Change history is announced on this page (/changelog)ship_to)country accepts only JP, the currently shippable country (ISO 3166-1 alpha-2)state (prefecture) accepts only the 47 official spellings (e.g. 東京都; 東京 or Tokyo returns 400). The accepted values are listed in the ShipTo schema of the API referencemin_stock filter is now based on immediately orderable stock and excludes preorderable quantities of preorder products