# ShipMonk API Documentation > The ShipMonk API enables developers to build custom integrations between ShipMonk and third-party software. ## Guides - [Introduction](https://apidocs.shipmonk.com/docs/intro.md) - [Key Concepts](https://apidocs.shipmonk.com/docs/concepts.md): ShipMonk App Core Concepts - [Obtaining Your API key](https://apidocs.shipmonk.com/docs/api-key.md) - [Terminology](https://apidocs.shipmonk.com/docs/definitions.md) - [Retrieve a List of Products](https://apidocs.shipmonk.com/docs/retrieving-a-list-of-products.md) - [Creating an Order](https://apidocs.shipmonk.com/docs/creating-an-order.md): This guide will walk you through creating an order for the first time using the ShipMonk API. - [Sync ShipMonk Inventory Levels](https://apidocs.shipmonk.com/docs/sync-shipmonk-inventory-levels.md) ## API Reference - [Getting Started](https://apidocs.shipmonk.com/reference/common.md): The ShipMonk API enables developers to build custom integrations between ShipMonk and third-party software. - [Webhooks](https://apidocs.shipmonk.com/reference/webhooks.md) - [Shipment Notification](https://apidocs.shipmonk.com/reference/webhook-order-shipment-notification.md): Once the order is fulfilled, ShipMonk can notify the 3rd party software of such event via webhook or Marketplace via direct integration. The payload consists of tracking and packing information. Triggers for sending notification are: - once regular order is packed - batch is completed - wholesale order is picked up Notification is sent with delay which can be set per each store in ShipMonk OMS. Your endpoint URL can be set up in the store detail in ShipMonk OMS. Please note that Basic Auth (username and password) is supported only. We expect the status code 200 in response. When we receive another status call, we will be re-trying it for the next 3 days. To test it, place the order and submit it for fulfilment. You have to make sure the inventory is available and order is all right first (it has set the shipping service and the address is valid). In production the order is shipped by our warehouse employees, while for testing you will have to call our `complete-order` endpoint. Edge cases: - If the order is big and cannot fit into a single packaging, we will send out multiple packages. Each package has its own tracking number inside of packages array. - If the inventory of any SKU is not available, it is possible to manually split the order in the ShipMonk app and then we send Shipment Notification per each shipment. - If the order is split and send out within multiple days, we send the Shipment Notification just once (when the first package is sent out) `fulfilled_quantity` vs `ordered_quantity`: The value of these two fields might differ in case of partially fulfilled Orders. If a Product consists of `1x Item A` and `1x Item B`, when the customer orders 2 Products and the Shipment contains 1 piece of Item A and 2 pieces of Item B, then `ordered_quantity = 2` but `fulfilled_quantity = 1`. - [Order status change](https://apidocs.shipmonk.com/reference/webhook-order-status-change.md): As an order progresses from initial import to full fulfillment, it transitions through multiple statuses. ShipMonk can notify external systems of these status changes via webhooks. ## Supported Order Webhooks Currently ShipMonk supports these order-related webhooks. - Order being back-ordered (`processing_status`: `back-order`) - Order is unable to submit (`processing_status`: `unable_to_submit`) - Order is queued to submit (`processing_status`: `queued_to_submit`) - Order is subscription - Order (`processing_status`: `subscription`) - Order is package-forwarding - Order (`processing_status`: `package_forwarding`) - Order is put to on hold (`processing_status`: `on_hold`) - Order is submitted (`processing_status`: `submitted`) - Order is being picked (`processing_status`: `pick_in_progress`) - Order is being packed (`processing_status`: `pack_in_progress`) - Order is packed (`processing_status`: `packed`) - Order is awaiting pickup (`processing_status`: `awaiting_pick_up`) - Order is awaiting carrier processing (`processing_status`: `awaiting_carrier_processing`) - Order is en route (`processing_status`: `en_route`) - Order is delivered (`processing_status`: `delivered`) - Order is undeliverable (`processing_status`: `undeliverable`) - Order is shipped, but it’s untrackable (`processing_status`: `shipped_untrackable`) - Order cancellation requested (`processing_status`: `cancellation_requested`) - Order is cancelled (`processing_status`: `cancelled`) All order-related webhooks are closely tied to the order’s processing-status. Each webhook is triggered by a change in the processing-status, reflecting key moments in the order lifecycle. ## Payload Structure (JSON Schema) All order-related webhooks share the same JSON schema, which matches the response of our GET endpoint for retrieving a single order. - [Return status change](https://apidocs.shipmonk.com/reference/webhook-return-status-change.md): ## Supported Return Webhooks All return-related webhooks are closely tied to the status of the return. Each webhook is triggered by a specific status transition, marking important stages in the return process. - Return created (`status`: `status_created`) - Return in progress (`status`: `in_progress`) - Return en route (`status`: `en_route`) - Return returned (`status`: `returned`) ## Payload Structure (JSON Schema) The payload of each return-related webhook matches the structure of a single return object as returned by the `GET /v1/integrations/returns-list` endpoint. While the `GET /v1/integrations/returns-list` endpoint responds with an array of return objects (`returns-list` field), each webhook delivers the full data of one return in the same format. This allows for easy reuse of the return model across both API responses and webhook events. - [Receiving status change](https://apidocs.shipmonk.com/reference/webhook-receiving-status-change.md): ## Supported Receiving Webhooks All receiving-related webhooks are closely tied to the status of the receiving. Each webhook is triggered when the receiving transitions to a specific `status`, reflecting key milestones in the receiving process. - Receiving awaiting (`status`: `awaiting`) - Receiving in progress (`status`: `in_progress`) - Receiving arrived (`status`: `arrived`) - Receiving received (`status`: `received`) - [Create or Update Receiving](https://apidocs.shipmonk.com/reference/post-v1-integrations-receiving.md): ## General description - ERP push to ShipMonk - `items.[].lot` or any of its property can be null ## ASN & Receiving Key - When updating a Receiving, the identifying properties are `receiving_key` and `asn` in this order. - In case both are supplied - First, Receiving is retrieved by `receiving_key`. If found, it is updated with new ASN if current ASN is different than `asn` in the request body. - If not found, Receiving is retrieved by `asn`. If found, it is updated with new `receiving_key` in the request body. - If not found, new Receiving is created with `receiving_key` and asn being its unique identifiers. - In case only asn is supplied - First, Receiving is retrieved by `asn`. If found, `receiving_key` of the Receiving is left as-is as it cannot be deleted upon setting up. - If not found, new Receiving is created with `asn` being its unique identifier. - In case only `receiving_key` is supplied - The request is rejected, as `asn` is required field. ## LineKey - When item objects are supplied with `line_key` string field, these items are then uniquely identified and can be referenced by it, if needed to change expected quantity. - Line Key must be unique per receiving. - Null/missing values are also expected. Such lines are then grouped by product and lot if supplied multiple times in the POST request. - [Retrieve List of Receivings](https://apidocs.shipmonk.com/reference/get-v1-integrations-receivings-list.md) - [Get Receiving](https://apidocs.shipmonk.com/reference/get-v1-integrations-receiving.md): ## ASN & Receiving Key When retrieving a Receiving, you must supply either the receivingKey or asn parameter. - If both are supplied, they must both match a single Receiving. - Supplying only one of the parameters is strongly advised. ## LineKey When item objects are supplied with a line_key string field, those items are uniquely identified and can be referenced by it later — for example, to change expected quantity. Line Key must be unique per receiving. - line_key is optional. Null or missing values are expected and supported. - Lines without a line_key can still be updated: they are matched by product and lot. If a product and lot combination are specified multiple times in a single POST request, they are grouped and their quantities summed. - On update, if exactly one existing line matches a given product and lot, that line is updated. - If multiple keyless lines share the same product and lot, they cannot be told apart and are replaced as a group, with the request treated as the source of truth. - Supply a line_key whenever you need to reliably target a specific line — especially when a receiving has more than one line for the same product and lot. - [Complete Receiving](https://apidocs.shipmonk.com/reference/post-v1-integrations-sandbox-complete-receiving.md): Simulates the completion of a receiving in your Sandbox environment. This action is available for testing purposes only and cannot be used in production. Use the completion_mode field to control how the simulation behaves: fully_received accepts all expected units, while short_received, excess_received, and partially_received simulate discrepancies that may leave the receiving open or generate exceptions. ## ASN & Receiving Key To identify the target receiving, you must supply either receiving_key or asn. - [Retrieve List of Receipts](https://apidocs.shipmonk.com/reference/get-v1-integrations-receipts-list.md) - [Create or Update Return](https://apidocs.shipmonk.com/reference/post-v1-integrations-returns.md) - [Retrieve List of Returns](https://apidocs.shipmonk.com/reference/get-v1-integrations-returns-list.md) - [Get Return](https://apidocs.shipmonk.com/reference/get-v1-integrations-returns.md): DEPRECATED – please use Retrieve List of Returns instead with filter for RMA. - [Complete Return](https://apidocs.shipmonk.com/reference/post-v1-integrations-sandbox-complete-return.md): This endpoint simulates the full return lifecycle on Sandbox environment. It can't be used in production! The return goes through arrival, check-in, receiving, grading, and completion based on the specified completion mode and disposition. ## Completion Modes Completion mode changes how many units are received of the FIRST item in the return. Other items are always fully received. | Mode | Description | Constraint | |------|-------------|------------| | `fully_received` | Receives the complete expected quantity | None | | `short_received` | Receives one less unit than expected | Expected quantity must be greater than 1 | | `excess_received` | Receives one more unit than expected | None | | `partially_received` | Receives only 1 unit regardless of expected quantity | Expected quantity must be greater than 1 | ## Dispositions | Disposition | Constraint | |-------------|------------| | `returned_to_inventory`| None | | `reworked` | Account must have rework feature enabled | | `dispose` | None | | `donate` | None | | `return_to_merchant` | None | - [Create or Update Order](https://apidocs.shipmonk.com/reference/post-v1-integrations-order.md): This endpoint can be used to create an order. The orders are typically pushed to ShipMonk from the 3rd party software. The Create Order endpoint does not create duplicate entries when both the `store_id` and `order_key` are the same. Instead, it updates the existing order. *NOTE: Resending an Order with a different `order_key` will result in Order duplication.** The order can be in following 4 statuses: - `unfulfilled` will create order for ShipMonk to process - `cancelled` will create cancelled order or cancel existing order - `fulfilled` will create order in status "Fulfilled by 3rd party" or change existing order status to that status or not perform any action if order was fulfilled by ShipMonk - `onHold` will create order in status onHold or put an existing order on hold. Can be useful: - if the field `warehouse` is not given, ShipMonk resolves it based on inventory & shipping costs - the field `custom_data` can be used for any data that you need to store and then receive back in shipment notification - the field `attributes` is only used for a custom development and in most of the cases it won't be needed - if the field submit_at is not given, order is submit according to store settings. ## Recipient Tax ID The **recipient_tax_id** field is an optional parameter when submitting an order through the API. However, it is **mandatory** for international shipments to certain countries, such as Mexico, Brazil, and South Korea. This field plays a role in customs clearance, ensuring accurate calculation of duties and taxes at the destination. ### How it's used For orders shipping to destinations where a recipient tax ID is mandatory, failure to include this field on the shipping label will result in the order being placed in the **"Recipient Tax ID Required" Action Required status**. Without a valid tax ID, carriers may reject the shipment, returning it to the sender. ### Best Practices To prevent delays, collect the `recipient_tax_id` from the recipient at checkout. This information is unique to the individual or entity receiving the shipment. ### Resolving Missing Recipient Tax ID Issues To address a missing recipient tax ID, you can update the `recipient_tax_id` in one of two ways: - **Via API**: Submit the missing tax ID programmatically using the appropriate endpoint. - **Manually**: Edit the order details directly in the ShipMonk App. Additional Resources For more information, including a current list of countries requiring a recipient tax ID, consult the [Action Required Orders](https://support.shipmonk.com/s/article/Action-Required-Orders) documentation. Refer specifically to the **"Recipient Tax ID Required"** section for detailed guidance and troubleshooting steps. ## Lot requirements Settings for lot requirements (lot, minimum shelf life, etc.) depend on your account settings. Contact your happiness manager to enable lot management. It is possible to set minimum shelf life for the whole order, per order item, or specific lot requirements per order item. - If you set the minimum shelf life for the whole order, you can't use settings at the item level. - If you set the minimum shelf life for an order item, you can't set specific lot controls for the same order item. If the lot requirement is not applicable to the mapped bundle, the order is accepted, but the item mapping ends with action required and you have to update the bundles or set different lot requirements. You can override the requirements from public API manually in the application. New request from API will override the manual settings, also empty lot settings will remove existing lot restrictions. - [Get Order](https://apidocs.shipmonk.com/reference/get-v1-integrations-orders.md): This endpoint can be used to retrieve data from the order you are calling.The order can be in following 4 statuses (field order_status): - `unfulfilled` indicates an order is ready for ShipMonk to process - `cancelled` indicates an order was cancelled - `fulfilled` indicates an order has been marked as "Fulfilled by 3rd party", unless already fulfilled by ShipMonk - `onHold` indicates an order is placed on hold You can retrieve orders from all of your stores. In case you have not unique orderKeys across stores you can specify the storeId. - [Retrieve List of Orders](https://apidocs.shipmonk.com/reference/get-v1-integrations-orders-list.md): When no filters are specified, the endpoint will return up to the first 1,000,000 orders, based on selected ordering. If filters are used, this endpoint will return a maximum of 10,000 orders. - [Complete Order](https://apidocs.shipmonk.com/reference/post-v1-integrations-sandbox-complete-order.md): Simulates warehouse shipment of an order in your Sandbox environment. Cannot be used in production. The order must be in a submitted status with available inventory, a valid address, and a valid shipping method. A shipment notification is sent after the delay configured for the store under Account Settings > Stores, defaulting to 20 minutes. For D2C orders, there is approximately a 1-minute delay (up to 5 minutes) between the order transitioning from awaiting pick up to en route. During this window, an awaiting shipment webhook is delivered to simulate the real fulfillment process. You can also simulate order completion directly in the ShipMonk UI. See our Sandbox guide for instructions. - [Submit Order](https://apidocs.shipmonk.com/reference/post-v1-integrations-submit-order.md): Submits an order for fulfillment or reschedules its submit date. Submitting an order makes it eligible for the operations team to begin fulfillment. Once submitted, the order enters the fulfillment pipeline and edit restrictions apply: - During picking, order items cannot be changed. - Once packed, no fields on the order can be changed. This endpoint serves two purposes: - Submit immediately — pass a submit_at timestamp in the past (or now) to release the order into the fulfillment queue right away. - Reschedule the submit date — even though submit_at can be set when creating an order, this is the simplest way to change it after the fact. When submit_at is in the future, inventory is reserved immediately and the order is released into the fulfillment queue at the scheduled time. - [Retrieve List of Products](https://apidocs.shipmonk.com/reference/get-v1-products.md): Results are not guaranteed to be consistent across paginated calls. As inventory is updated during fulfillment, products shift position in the sort order and may reappear on later pages. For consistent pagination, use the Products for Inventory Sync endpoint instead. - [Create Product](https://apidocs.shipmonk.com/reference/post-v1-integrations-product.md): This endpoint allows merchants to create products within ShipMonk. Once created, product data is immutable via API — updates must be made via the ShipMonk web app. SKUs must be unique within the account. ShipMonk will reject non-unique SKUs with a 400 error. The required_packaging field defines the minimum packaging suitable for a product. When fulfilling an order, ShipMonk selects the smallest packaging type that satisfies every item in the shipment — for example, if an order contains one product that can ship in a poly mailer and another that requires a box, the entire order ships in a box. Field country_of_origin accepts a 2-letter ISO 3166-1 alpha-2 country code. ## Fragile products Fragile products must have required_packaging set to box. Submitting any other value will return a 400 error. - [Products for Inventory Sync](https://apidocs.shipmonk.com/reference/post-v1-integrations-products-search.md): Search for products based on a set of filters and sorting criteria. A cursor is returned that can be used by /integrations/products/search/paginate endpoint to iterate through the results. The search results are fixed at the time of the request. This guarantees that it's possible to iterate over the whole data set reliably without missing any products. The returned cursor is valid for 1 hour. A typical use-case might be inventory synchronization where products with updated inventory are fetched periodically, (for example fetching changes from the previous day 8am up until now). With the search results being fixed, the synchronization process can be implemented in a reliable way. One thing to note, the inventory_on_hand_last_updated_at field only captures the latest update so when a product was first updated the day before and then again on the current day, it will not be included in the results for yesterday only. - [Fetch results from Products for Inventory Sync](https://apidocs.shipmonk.com/reference/get-v1-integrations-products-search-paginate.md): Iterate over results from /integrations/products/search endpoint using the returned cursor or using the cursor provided by response of this request as nextCursor. The response is the same as the legacy /products endpoint (Retrieve List of Products). - [Retrieve List of Warehouses](https://apidocs.shipmonk.com/reference/get-v1-integrations-warehouses.md): Returns all enabled warehouses for the account associated with your API key. Warehouse IDs and identifiers are required across various endpoints and can be included in query parameters to filter results. ## Changelog - [v1.024](https://apidocs.shipmonk.com/changelog/v1-024.md) - [v1.023](https://apidocs.shipmonk.com/changelog/v1-023.md) - [v1.022](https://apidocs.shipmonk.com/changelog/v1-022.md) - [v1.021](https://apidocs.shipmonk.com/changelog/v1-021.md) - [v1.020](https://apidocs.shipmonk.com/changelog/v1-020.md) - [v1.019](https://apidocs.shipmonk.com/changelog/v1-019.md) - [v1.018](https://apidocs.shipmonk.com/changelog/v1-018.md) - [v1.017](https://apidocs.shipmonk.com/changelog/v1-017.md) - [v1.016](https://apidocs.shipmonk.com/changelog/v1-016.md) - [v1.015](https://apidocs.shipmonk.com/changelog/v1-015.md)