Amazon SP-API Switches Japan Fulfillment Preview Timestamps to ISO 8601 Format
Amazon will change the Japan marketplace getFulfillmentPreview response on May 27 2025 to return ISO 8601 timestamps (e.g., 2025-05-27T14:30:00Z) instead of UNIX‑epoch integers such as 1748621400. The estimatedDeliveryDate field for the scheduled delivery speed will now be a string, requiring code changes to date parsing.
Overview
Amazon is revising the getFulfillmentPreview call in the Selling Partner API for the Japan marketplace. Starting May 27 2025, the operation will return delivery dates as ISO 8601 timestamps instead of the current UNIX‑epoch integers. Sellers and developers who rely on Japan‑specific fulfillment previews must adjust their date‑parsing logic now to avoid order‑processing errors after the switch.
Key Points
- Timestamp format change — Delivery windows for Japan will be delivered as strings like
2025-05-27T14:30:00Zrather than numeric values such as1748621400. - Scope limited to scheduled delivery — Only the scheduled delivery shipping speed category inside
getFulfillmentPreviewis affected; other speed categories remain unchanged. - Alignment with global standards — The new format matches the ISO 8601 representation already used for the United States, Europe, and other Amazon marketplaces, eliminating the lone regional exception.
- Effective date set — The transition becomes mandatory on May 27 2025, giving developers a clear deadline to test and deploy updates.
- Dual‑parser recommendation — Amazon suggests implementing a parser that first attempts ISO 8601 conversion and falls back to UNIX‑timestamp handling, ensuring continuity during the cut‑over period.
How the Change Works
- API response format update — When a seller requests a fulfillment preview for Japan with the scheduled delivery speed, the
estimatedDeliveryDatefield will now contain an ISO 8601 string (e.g.,2025-06-01T09:00:00Z). Previously the same field returned a plain integer representing seconds since 1 January 1970. - Parsing logic shift — Applications that previously called
new Date(UNIX_TIMESTAMP * 1000)must replace that logic with a standard ISO 8601 parser such asDate.parse(isoString). If the response still arrives as a number, the fallback routine should convert it by multiplying by 1,000 before creating a JavaScript object.
Analysis & Recommendations
Why This Matters
If developers keep using the old UNIX‑timestamp conversion, orders for Japan may receive incorrect delivery dates or fail processing after May 27 2025. Aligning Japan with global ISO 8601 format simplifies multi‑marketplace code but forces an urgent code revision and testing to avoid disruptions.
Key Takeaways
- Timestamp format change: ISO 8601 strings like 2025-05-27T14:30:00Z replace UNIX integers (e.g., 1748621400) for Japan scheduled delivery.
- Effective date: mandatory switch on May 27 2025.
- Scope limited to the scheduled delivery speed category within getFulfillmentPreview; other speeds stay unchanged.
- Amazon recommends a dual‑parser: try ISO 8601 conversion first, fallback to UNIX‑timestamp handling.
Recommended Actions
- →Update your integration code (e.g., in the fulfillment preview module) to replace `new Date(response.estimatedDeliveryDate * 1000)` with `new Date(...
- →Add a utility that first uses `Date.parse(isoString)` and, if NaN, multiplies the numeric value by 1,000; commit the change in your code repository.
- →Create unit tests in your CI that feed both `1748621400` and "2025-05-27T14:30:00Z" and assert the resulting Date objects are identical before the ...
Comments
Join the discussion
Log in or create an account to share your thoughts on this update.
No comments yet. Be the first to share your thoughts!