v1.009

Added shippedAtStart and shippedAtEnd filter parameters to the List Orders API endpoint.

🚀 New Endpoints

None

🛠 Schema & Property Updates

• List Orders (GET /v1/integrations/orders-list → shippedAtStart): New optional query parameter shippedAtStart (string|null, date-time format). When provided, filters results to orders shipped at or after this timestamp. Defaults to null.

• List Orders (GET /v1/integrations/orders-list → shippedAtEnd): New optional query parameter shippedAtEnd (string|null, date-time format). When provided, filters results to orders shipped before this timestamp. Defaults to null.

Added sscc (Serial Shipping Container Code) support to the receiving API — both as an optional input field when submitting receiving lines and as a field always present in the response.

🚀 New Endpoints

None

🛠 Schema & Property Updates

• Receiving Line Input (POST /v1/integrations/receiving → items[].sscc): New optional field sscc (string|null, exactly 18 characters) added to each line item in the receiving request body. Allows callers to associate a Serial Shipping Container Code with a specific receiving line at submission time.

• PublicApiReceivingLineOutput (sscc): New required response field sscc (string|null) added to every receiving line in the response. Returns the SSCC associated with the line, or null if none was provided.

Enforced box packaging requirement for fragile products — both in code and API documentation.

📖 Documentation & Constraints Changes

• Product Push Endpoint (POST /v1/integrations/products): Added a Fragile products section to the endpoint description clarifying that when a product is marked as fragile, the required_packaging field must be set to box. This constraint is now also enforced in code. 🔴 BREAKING — Requests creating or updating a fragile product with a required_packaging value other than box will be rejected.

Added support for the new merchant facility warehouse type in preparation for the upcoming EVCN feature.

🛠 Schema & Property Updates

Enums

• WmsType: Added the value merchant_facility to the ShipMonk_WmsConnector_Order_ValueObject_WmsType enum. This new warehouse type represents merchant facility warehouses used by the upcoming EVCN feature. API consumers may encounter this value in the warehouse_wms_type field of order warehouse details but should not need to send it — dedicated endpoints for "pickup from merchant facility" and "package forward" fulfillment types will be introduced separately.

Switched API changelog versioning from semantic versioning (vX.Y.Z) to sequential numbering (v1.###).

📖 Documentation & Constraints Changes

• Version Numbering: The API changelog now uses a sequential v1.### versioning scheme instead of semantic versioning (MAJOR.MINOR.PATCH). Each release increments the number by 1 regardless of change severity (e.g., v1.003 → v1.004). Breaking changes continue to be marked with 🔴 BREAKING. The reason for this change is to make versioning easier — since only one live version is supported at a time, a simple sequential number is sufficient.

Adds lot requirement settings to order creation, allowing merchants to specify minimum shelf life and specific lot controls at the order level or per individual order item.

🛠 Schema & Property Updates

Lot Requirements for Order Creation

Create Order (POST /v1/integrations/order): Added two new optional fields to the request body to support lot management during order creation.

• minimum_shelf_life_days (integer|null) — Sets a minimum shelf life requirement for all items in the order. The value must be greater than 0. When set at the order level, per-item lot_requirements must not be used.

• items[].lot_requirements (object|null) — Allows specifying lot controls per individual order item. Cannot be combined with the order-level minimum_shelf_life_days. Contains:

  • minimum_shelf_life_days (integer|null) — Minimum shelf life for this specific item (value must be > 0). Cannot be combined with lot_controls on the same item.
  • lot_controls (array<object>) — List of specific lot requirements for this item. Each entry may contain:
    • lot_number (string|null) — The required lot number.
    • expiration_date (string|null, format: date) — The required expiration date in ISO 8601 format (e.g. 2026-12-31).

📖 Documentation & Constraints Changes

• Create Order (POST /v1/integrations/order): Added a "Lot requirements" section to the endpoint description. It documents the mutual exclusivity rules between order-level and item-level lot settings, explains that lot requirements not applicable to a mapped bundle will result in the item mapping ending with "action required", and clarifies that new API requests override any manually set lot requirements (and that sending empty lot settings removes existing restrictions). Contact your happiness manager to enable lot management.

Adds lot control settings to product creation, fix documentation for pagination.

🚀 New Features

Lot Control Settings for Product Creation

• Create Product (POST /v1/integrations/product): Added a new optional nullable property lot_control_settings to the request body. This allows configuring lot tracking behavior per product with the following options:
  • is_lot_number_required (boolean) - whether lot number is required for the product
  • is_expiration_date_required (boolean) - whether expiration date is required for the product
  • is_labeled_with_expiration_date_only (boolean) - whether the product is labeled with expiration date only

🛠 Schema & Property Updates

Stricter Validation Constraints

Pagination and identifier parameters across several endpoints now formally enforce validation constraints that reflect existing server-side behavior:

• Retrieve Orders (GET /v1/integrations/orders-list):

  • page now enforces minimum: 1
  • pageSize now enforces minimum: 1 and maximum: 100

• Fetch Results from Products for Inventory Sync (GET /v1/integrations/products/search/paginate):

  • pageSize now enforces minimum: 1 and maximum: 500

• Retrieve Receipts (GET /v1/integrations/receipts-list):

  • page now enforces minimum: 1
  • pageSize now enforces minimum: 1 and maximum: 100
  • warehouseId now enforces minimum: 1

ReturnItemInput - Quantity Validation

• expected_quantity in Fulfillment_IntegrationsBundle_ApiResource_ReturnItemInput: Now enforces exclusiveMinimum: 0, meaning the value must be strictly greater than zero.

Added new endpoints for supporting high-volume inventory synchronization.

🚀 New Endpoints

To support high-volume inventory synchronization and consistent data retrieval, the following endpoints were added:

• Products for Inventory Sync (POST /v1/integrations/products/search): A new endpoint designed for product synchronization, mainly based on the time of last inventory on hand update. It allows searching with filters and returns a cursor that fixes the result set ensure reliability during synchronization.
• Fetch results from Products for Inventory Sync (GET /v1/integrations/products/search/paginate): A companion endpoint used to iterate through the results of the initial search using the provided cursor.

💡 Usage Example

Here's an example of how to use the new product search endpoints for inventory synchronization:

Step 1: Create a search with filters

POST /v1/integrations/products/search
{
    "filters": {
        "inventory_on_hand_last_updated_at": {
            "is_after_or_equal": "2025-01-01T00:00:00Z",
            "is_before_or_equal": "2025-01-31T23:59:59Z"
        },
        "search": "chair"
    },
    "sort": {
        "sort_by": "inventory_on_hand_last_updated_at",
        "order_by": "DESC"
    }
}

Response:
{
    "cursor": "eyJmaWx0ZXJzIjp7fSwic29ydCI6e319...",
    "total": 150
}

Step 2: Paginate through results

GET /v1/integrations/products/search/paginate?cursor=eyJmaWx0ZXJzIjp7fSwic29ydCI6e319...&pageSize=50

Response:
{
    "data": [
        { "id": 123, "name": "Office Chair", ... },
        { "id": 124, "name": "Gaming Chair", ... },
        ...
    ],
    "total": 150,
    "next_cursor": "eyJmaWx0ZXJzIjp7fSwic29ydCI6e320..." // Use for next page, or null if no more results
}

Step 3: Continue pagination

GET /v1/integrations/products/search/paginate?cursor=eyJmaWx0ZXJzIjp7fSwic29ydCI6e320...&pageSize=50

// Repeat until next_cursor is null

🛠 Schema & Property Updates

Product Data Models

• inventory_on_hand_last_updated_at: Added this field to ProductListOutput. It tracks the latest update to physical inventory (e.g., from receiving or packing) and is used as a filter in the new search functionality.

📖 Documentation & Constraints Changes

• GET /v1/products (Retrieve List of Products): Added a disclaimer that this endpoint does not guarantee a consistent result set between paginated calls. Users are encouraged to use the new /integrations/products/search for reliable syncs.
• Search Filters: Documentation for product searching now specifies that searching for SKUs and names allows for substring matches, while barcodes require an exact match.

Bug fixes for query parameter casing and removal of unsupported legacy field.

❌ Removed

• 🔴 BREAKING - shipping_payment_terms: The shipping_payment_terms property has been removed from the API as it is no longer supported and should not be used.
  • Replacement: This field is deprecated with no direct replacement.
  • Migration: Remove any references to shipping_payment_terms from your integration code. If you were relying on this field, please contact support to discuss alternative solutions for managing shipping payment terms.

🐛 Fixed

Query Parameter Casing

Fixed a bug that was causing query parameters to be documented in snake_case format instead of the correct camelCase format. This ensures consistency across the API and matches JavaScript naming conventions.

Retrieve List of Orders (GET /v1/integrations/orders-list)

The following query parameters are now correctly documented in camelCase:

• page_size → pageSize: Number of items per page
• sort_order → sortOrder: Sort direction (ascending/descending)
• order_keys → orderKeys: Filter by order keys
• order_numbers → orderNumbers: Filter by order numbers
• order_status → orderStatus: Filter by order status
• order_type → orderType: Filter by order type
• updated_at_start → updatedAtStart: Filter by update date range start
• updated_at_end → updatedAtEnd: Filter by update date range end

Retrieve List of Receipts (GET /v1/integrations/receipts-list)

The following query parameters are now correctly documented in camelCase:

• page_size → pageSize: Number of items per page
• sort_order → sortOrder: Sort direction (ascending/descending)
• warehouse_id → warehouseId: Filter by warehouse identifier
• completed_at → completedAt: Filter by completion timestamp