Tutorials

2026-04

2026-04 Release Notes

Fulfillments

New Features

  • Source Breakdown for Fulfill and Pack: The POST /fulfillments/{fulfillment_id}/fulfill and POST /fulfillments/{fulfillment_id}/pack endpoints now accept an optional source_breakdown on each line item, allowing callers to specify exactly how quantities should be sourced from different fulfillment states.

Fulfill (POST /fulfillments/{fulfillment_id}/fulfill)

Each line item may include an optional source_breakdown object with three fields:

FieldTypeDescription
quantity_from_pickednumber (double)Quantity to source from the picked state.
quantity_from_packednumber (double)Quantity to source from the packed state.
quantity_from_not_startednumber (double)Quantity to source from the not-started state.

When provided, all three fields are required and must sum to the parent quantity.

Pack (POST /fulfillments/{fulfillment_id}/pack)

Each line item may include an optional source_breakdown object with two fields:

FieldTypeDescription
quantity_from_pickednumber (double)Quantity to source from the picked state.
quantity_from_not_startednumber (double)Quantity to source from the not-started state.

When provided, both fields are required and must sum to the parent quantity. Source breakdown is not allowed when the quantity is negative (unpacking).

Schema Corrections

  • Fulfill response structure: The POST /fulfillments/{fulfillment_id}/fulfill response schema now correctly wraps id and version inside a data object, matching the actual API behavior and consistent with the pack and pick endpoint response schemas. Clients generated from the previous (incorrect) schema may need to update to read from the data wrapper.

Inventory

We have redesigned the inventory endpoints to use POST request bodies instead of query parameters, added new response fields, and improved consistency across the API.

Breaking Changes

  • POST /inventory (was GET): Now accepts a JSON request body (InventoryRequest) instead of query parameters. The response returns a flat array of Inventory objects instead of a { data: [...] } wrapper.
  • POST /inventory_levels (was GET): Now accepts a JSON request body (InventoryLevelsRequest) instead of a JSON-encoded options query parameter. The response returns a flat array of InventoryLevel objects instead of a { data: [...] } wrapper.
  • GET /inventory_levels/{product_id}: The inactive parameter (integer 0/1) has been renamed to include_inactive (boolean). The totals object has been removed from the response.
  • Quantity field changes: inventory_level and quantity have been split into current_inventory_level and quantity_to_procure. In older APIs, stock required for fulfillments and services was represented as negative quantity values. In the 2026-04 API, this is now represented as positive quantity_to_procure values. This is not a straight renaming — consumers relying on negative values in quantity or inventory_level must update their logic.

Updated Endpoints

  • POST /inventory: List inventory records. Supports filtering by product_id, variants, after, before, include_deleted, pagination via size (max 5000), and sort_direction.
  • GET /inventory/{product_id}: List inventory records for a single product. Improved product_id and variants parameter descriptions to clarify variant matching behavior.
  • POST /inventory_levels: List inventory levels. Now supports group_variants and to_be_procured_only filters. The out_of_stock_only and group_by parameters have been removed. product_ids and root_product_ids are now documented as mutually exclusive. size now has an explicit maximum of 10,000.
  • GET /inventory_levels/{product_id}: List inventory levels for a single product.

Schema Changes

Inventory

  • inventory_level has been renamed to current_inventory_level.
  • New fields: quantity_to_procure, average_cost, deleted_at, version, reorder_target, reorder_method.

InventoryLevel

  • quantity has been renamed to current_inventory_level.
  • New fields: root_product_id, quantity_to_procure.
  • Removed: levels object (containing producible and on_hand).

Deprecations

  • GET /inventory: Deprecated. Please use POST /inventory instead.
  • GET /inventory_levels: Deprecated. Please use POST /inventory_levels instead.

Gift Cards

New 2026-04 Gift Card and Gift Card Transaction endpoints are now available. These endpoints follow the 2026-04 API conventions while delegating to the same underlying gift card business logic.

New Endpoints

Gift Card Resource

MethodPathScopeNotes
POST/api/2026-04/gift_cards🔒 gift_cards:write:issueCreate and activate
GET/api/2026-04/gift_cards🔒 gift_cards:readList gift cards
GET/api/2026-04/gift_cards/by_number/{card_number}🔒 gift_cards:readGet by number
GET/api/2026-04/gift_cards/by_id/{id}🔒 gift_cards:readGet by ID
DELETE/api/2026-04/gift_cards/by_number/{card_number}🔒 gift_cards:write:issueVoid by number
DELETE/api/2026-04/gift_cards/by_id/{id}🔒 gift_cards:write:issueVoid by ID

Gift Card Transaction Resource

MethodPathScopeNotes
POST/api/2026-04/gift_cards/{card_number}/transactions🔒 gift_cards:write:redeemCreate transaction
DELETE/api/2026-04/gift_cards/transactions/{transaction_id}🔒 gift_cards:write:redeemReverse redemption
GET/api/2026-04/gift_cards/transactions/{transaction_id}🔒 gift_cards:readSupports system_id query param

Key Changes

  • Response structure: All responses return the resource inside a top-level data key in the response object.
  • Monetary values as strings: Fields such as balance, total_sold, total_redeemed, and amount are now returned as strings for precision.
  • POST returns 201: Create endpoints now return 201 Created instead of 200 OK.
  • system_id support: The GET gift card by transaction ID endpoint accepts an optional system_id query parameter (defaults to x-series, also supports e-series).

Updated 7 days ago