Changelog
Back to All

v1.034

about 2 hours ago

The orders list can now be searched like the ShipMonk app and filtered by store, and every order says where it came from and how it relates to merged orders.
Merchants moving from the internal order list to the public API can find an order by its storefront number together with its replacements, and limit results to selected stores. Every order object now also carries its source, the merge order it was merged into and the orders merged into it, so replacement and merge checks can be done with GET /v1/integrations/orders-list and GET /v1/integrations/orders alone.

🚀 New Endpoints

None

🛠 Schema & Property Updates

Search and Store Filter on the Orders List

  • Retrieve Orders (GET /v1/integrations/orders-list):
    • search (string, optional, 1 to 100 characters) - Searches orders the same way as the search box in the ShipMonk app. Combined with the other filters by AND.
      • Matches orders by their order number, reference number, customer order number, PO number and other order references, such as release number or job number.
      • Each of these fields is split into words at spaces and at the characters #, -, , and :. An order matches when any word starts or ends with the search text. A leading # in the search text is ignored, so #2643432 returns the same results as 2643432. URL-encode # as %23.
      • For example, searching 2643432 finds orders with the values #2643432 (a standard order), 2643432-01 (a replacement order) and Merged: 2643432, 2700965 (a merge order).
      • The search also matches tracking numbers, order_key, customer name, zip code, customer email and address, serial numbers, freight BOL, load, carrier and shipment tracking numbers, and RMA or return order numbers.
      • Leading and trailing whitespace is trimmed. A search containing only whitespace is treated as if it was not sent.
    • storeIds[] (array<integer>, optional, 1 to 100 values, each at least 1) - Returns only orders of the given stores. You can find a store ID in the ShipMonk app under Account Settings > Stores > Store ID, and every order in the response contains its store_id. IDs of stores outside your account are ignored, so a list holding only such IDs returns no orders. Duplicates are ignored.

Order Source and Merge Links

All three fields are added to the order object (PublicApiOrderDetailOutput), which is shared by GET /v1/integrations/orders and GET /v1/integrations/orders-list. They are always present.

  • source (string) - How the order came to exist, with the same values as in the ShipMonk app:
    • manual - created in the ShipMonk app.
    • imported - synced from a store integration or created through the public API.
    • manually_imported - uploaded from a file.
    • merged - a merge order combining several orders of one customer, see merged_orders.
    • cloned - a copy of another order created in the ShipMonk app.
    • splitted - a part of an order that was split manually or automatically, for example to ship hazardous materials or items that do not fit into one box separately.
    • oversize_split - a part of an order split automatically so that each unit of an oversized item ships separately.
    • claim_reship - a reshipment created from a claim.
    • automated_bonded_clearance_order - an order created automatically by ShipMonk to move your inventory from a bonded warehouse to another of your warehouses.
    • wholesale_split and package_forwarding_split - parts of split orders that appear only on historical orders.
  • merged_to_order (object|null) - null unless this order was combined with other orders of the same customer into a merge order. In that case this order is cancelled and this field points to the merge order that ships in its place, so a cancelled order with a non-null merged_to_order was cancelled by the merge, not by a person. If the merge order is later cancelled, the link is removed and this field is null again, while this order stays cancelled.
  • merged_orders (array<object>) - For a merge order (source is merged), the orders that were combined into it, oldest first. Empty for all other orders, and also empty after the merge order is cancelled.

Each related order (PublicApiRelatedOrderOutput) contains:

  • order_key (string) - order_key of the related order. It is unique only within its store.
  • order_number (string) - order_number of the related order.
  • store_id (integer) - ID of the store the related order belongs to. Pass it as storeId together with order_key to GET /v1/integrations/orders to fetch the related order. Merge links always point to an order in the same store.

Enums

  • PublicApiOrderSource: New enum (ShipMonk_PublicApi_Order_Output_PublicApiOrderSource) with the values manual, imported, manually_imported, merged, cloned, splitted, oversize_split, wholesale_split, package_forwarding_split, claim_reship and automated_bonded_clearance_order, used by source.

📦 New Support Schemas

The following schemas were introduced to support the order source and the merge links:

  • ShipMonk_PublicApi_Order_Output_PublicApiOrderSource
  • ShipMonk_PublicApi_Order_Output_PublicApiRelatedOrderOutput

📖 Documentation & Constraints Changes

None

No endpoints, fields or enum values were removed. The search and the store filter are optional query parameters and the three fields are additions to the response, so this version is backward-compatible. Clients that reject unknown properties must accept the three new fields.