Update: Vendor Orders API now supports variable weight products
Amazon upgraded Vendor Orders API v1 in early 2024 to add a `unitOfMeasure` field on every purchase‑order line‑item, supporting weight‑based pricing (e.g., LB, KG). A 90‑day transition ends soon, after which null values will be rejected.
Amazon has upgraded Vendor Orders API version 1 to include a new unitOfMeasure attribute, enabling vendors to transmit weight‑based pricing such as “per pound” or “per kilogram.” The change became active in early 2024 and now appears on every endpoint that returns purchase‑order line items. Vendors that sell bulk foods, raw materials, or any product measured by variable weight must adjust their integration or risk pricing mismatches and order‑processing delays.
Key Points
New attribute introduced — The unitOfMeasure field is now part of every purchase‑order line‑item response, explicitly stating the measurement unit (for example, LB for pounds or KG for kilograms).
Legacy behavior preserved — When the field is absent, the API continues to treat the item as a standard “each” SKU, ensuring that existing non‑weight workflows remain unaffected.
Endpoints updated — The variable appears in getPurchaseOrders, getPurchaseOrder, and any future line‑item pricing calls, delivering a uniform data model throughout the order lifecycle.
Compatibility caveat — Integrations that simply ignore the new field will still run, but they will misinterpret weight‑based prices as per‑unit prices, potentially causing over‑charging or under‑charging.
90‑day update window — Amazon advises vendors to modify their code within the next 90 days, after which validation rules will enforce a non‑null unitOfMeasure for every weight‑based SKU.
Sandbox reflects reality — The testing environment now returns realistic unitOfMeasure values for sample bulk products, allowing developers to verify calculations before moving to production.
How the Vendor Orders API Handles Variable Weight Products
Identify weight‑based SKU — Vendors assign a unitOfMeasure value such as LB or KG to any catalog entry that is sold by weight, linking the unit directly to the SKU’s price definition. : A bulk coffee bean SKU is created with and a listed price of $12.99 per pound.
Analysis & Recommendations
Why This Matters
Vendors selling bulk foods or raw materials must read the new `unitOfMeasure` to calculate correct totals; otherwise prices may be over‑ or under‑charged. The enforcement deadline forces immediate code updates to avoid order rejections and margin loss.
Key Takeaways
The `unitOfMeasure` attribute (e.g., LB, KG) is now included in getPurchaseOrders and getPurchaseOrder responses.
If the field is absent, the API defaults to treating the SKU as an “each” item, risking large pricing mismatches.
Amazon will enforce a non‑null `unitOfMeasure` for weight‑based SKUs after a 90‑day window from early 2024.
Sandbox now returns realistic `unitOfMeasure` values for sample bulk products for testing.
Recommended Actions
→Update your order‑processing code to read `unitOfMeasure` from the Vendor Orders API response (Seller Central > Developer Console > Integration).
→Add or verify `unitOfMeasure` (LB/KG) on all weight‑based catalog entries in your Amazon Vendor Central product feed.
→Run end‑to‑end tests in the sandbox and confirm totals (e.g., 2.5 KG × $8.00 = $20.00) before the 90‑day deadline.
API returns line‑item with unit — When a buyer places an order, calls like getPurchaseOrders now embed the unitOfMeasure alongside price, quantity, and currency, giving the vendor full visibility into the measurement context. Example: The response for an order of 5 lb of coffee includes "unitOfMeasure":"LB" and "price":12.99.
Calculate total cost — The vendor’s system multiplies the ordered weight by the per‑unit price to derive the line total; the API supplies the raw numbers but does not perform the arithmetic itself. Example: For a 5 lb request, the vendor computes 5 × $12.99 = $64.95 and records that amount as the line subtotal.
Validate presence of unit — During the transition period, Amazon’s validation service scans every weight‑based line item; if unitOfMeasure is null or missing, a warning appears in the vendor dashboard, prompting immediate correction. Example: An order for bulk spices lacking a unit triggers the alert “Weight‑based SKU missing unit of measure.”
Fallback to eaches — If a vendor’s integration still omits the field, the API defaults to treating the quantity as a count of individual units, which prevents order rejection but inflates or deflates the price dramatically. Example: The same coffee SKU without unitOfMeasure would be interpreted as five separate bags priced at $12.99 each, resulting in a mistaken total of $64.95 × 5 = $324.75.
Persist unit in downstream systems — After receiving the API response, vendors should store unitOfMeasure in their order‑management database so that downstream processes such as invoicing, tax calculation, and shipping can reference the correct measurement. Example: The order‑management table records sku, orderedQuantity, unitOfMeasure, and pricePerUnit, enabling accurate generation of a PDF invoice that shows “5 lb @ $12.99/lb = $64.95.”
Context: Before vs. After the Update
Before: Vendors could only convey price information on a per‑unit basis, forcing them to pre‑calculate a “per‑bag” price for bulk items, which often introduced rounding errors and inventory discrepancies.
After: The API now transmits the exact measurement unit, allowing vendors to keep a true per‑weight price in the catalog and letting Amazon’s ordering system request any fractional quantity without manual price adjustments.
Seller Impact
Vendors need to revise their order‑processing pipelines to read and apply the new field, or they risk significant pricing errors.
Update data mapping — Adjust integration code to detect unitOfMeasure and multiply price by the ordered quantity expressed in the same unit; for instance, a Java service can add a conditional block that checks if (unitOfMeasure != null) total = price * quantity;.
Revise catalog entries — Ensure every weight‑based SKU includes a correct unitOfMeasure value and that the listed price reflects cost per that unit; for example, change a tea SKU from “$8.00 each” to “$8.00 per kilogram” and set unitOfMeasure = "KG".
Test in sandbox — Run end‑to‑end simulations using the updated sandbox responses to confirm that line totals, taxes, and shipping fees align with the new weight logic; a test order of 2.5 kg of tea should return "unitOfMeasure":"KG" and a calculated total of 2.5 × $8.00 = $20.00.
Monitor validation alerts — Regularly check the vendor dashboard for “missing unit of measure” warnings and correct any catalog deficiencies before the enforcement deadline; a warning for SKU #B12345 can be cleared by adding unitOfMeasure = "LB" to that entry.
Adjust reporting — Extend internal analytics to include a “Weight Unit” column, enabling separate margin analysis for pound‑based versus each‑based products and improving profitability insights across mixed catalogs.
Synchronize pricing engines — Update any external pricing or ERP systems that consume the API so they recognize the unitOfMeasure field and apply the correct multiplication logic, preventing double‑counting of quantities.
Communicate with buyers — Notify retail partners that future purchase orders will contain explicit measurement units, reducing the need for manual clarification and streamlining the order‑confirmation process.
Document the change — Add a section to internal integration documentation describing the new field, its possible values, and the required calculation steps, ensuring that new team members inherit the correct handling procedures.
Plan for future extensions — Anticipate that Amazon may introduce additional units (e.g., ounces or grams) and design the code to handle any valid unitOfMeasure value dynamically rather than hard‑coding only pounds and kilograms.
By incorporating the unitOfMeasure attribute, vendors gain precise control over variable‑weight pricing, eliminate cumbersome workarounds, and align more closely with Amazon’s purchasing expectations. Prompt implementation protects against order rejections, preserves margin integrity, and positions sellers for smoother operations in weight‑sensitive categories.
Source: developer-docs.amazon.com
Comments
Join the discussion
Log in or create an account to share your thoughts on this update.
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!