openapi: 3.1.0
info:
title: ShipMonk Orders API
version: v1.024
description: The Orders surface of the ShipMonk public fulfillment API.
servers:
- url: https://api.shipmonk.com
description: Once you finish testing on Sandbox, our support team generates you Production API keys and store_id for production.
Just write us at api@shipmonk.com and we will handle it.
- url: https://sandbox.shipmonk.dev
description: 'Sandbox environment is used for preproduction testing. It allows you to play around without worries of corrupting
the data. We highly recommend using the Sandbox environment and run tests before going to Production. To get access to
the Sandbox, please contact the ShipMonk support team. Note: Sandbox access can only be requested by customers with signed
contracts.'
tags:
- name: Orders
paths:
/v1/integrations/order:
post:
operationId: post-v1-integrations-order
parameters: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Crate_OrderSyncOutput'
tags:
- Orders
security:
- api_key_header_Api-Key: []
description: '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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderInput'
summary: Create or Update Order
/v1/integrations/orders:
get:
operationId: get-v1-integrations-orders
parameters:
- in: query
name: orderKey
schema:
type:
- string
- 'null'
minLength: 1
maxLength: 255
default: null
required: false
description: Filter by the external system's unique order identifier (order_key). Returns only orders matching this
value; omit to skip this filter.
example: 327b5abd-017a-4504-a50d-54f1cea80269
- in: query
name: orderNumber
schema:
type:
- string
- 'null'
minLength: 1
maxLength: 255
default: null
required: false
description: Filter by the customer-facing order identifier (order_number). Returns only orders matching this value;
omit to skip this filter.
example: Order-123
- in: query
name: storeId
schema:
type:
- integer
- 'null'
minimum: 1
default: null
required: false
description: Filter by the internal numeric identifier of the store that owns the order. Omit to return orders across
all stores.
example: 123456
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: integer
data:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailOutput'
required:
- status
- data
tags:
- Orders
security:
- api_key_header_Api-Key: []
description: '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.'
summary: Get Order
/v1/integrations/orders-list:
get:
operationId: get-v1-integrations-orders-list
parameters:
- in: query
name: page
schema:
type: integer
minimum: 1
default: 1
required: false
description: 1-based page number to return. Defaults to 1.
example: 1
- in: query
name: pageSize
schema:
type: integer
minimum: 1
maximum: 100
default: 100
required: false
description: Number of results per page. Defaults to a server-configured value; check the response metadata for the
effective size.
example: 10
- in: query
name: sortOrder
schema:
$ref: '#/components/schemas/Fulfillment_PublicApiBundle_Enum_PublicApiOrdering'
default: ASC
required: false
description: 'Sort direction by internal order id: DESC (newest first) or ASC (oldest first).'
- in: query
name: orderKeys
schema:
type:
- array
- 'null'
items:
type: string
minLength: 1
maxLength: 255
default: null
required: false
description: Filter to orders whose order_key matches any value in this list.
- in: query
name: orderNumbers
schema:
type:
- array
- 'null'
items:
type: string
minLength: 1
maxLength: 255
default: null
required: false
description: Filter to orders whose order_number matches any value in this list.
- in: query
name: orderStatus
schema:
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_Enum_PublicApiOrderStatus'
- type: 'null'
default: null
required: false
description: Filter by current order status (see PublicApiOrderStatus enum); omit to return all statuses.
- in: query
name: orderType
schema:
anyOf:
- $ref: '#/components/schemas/ShipMonk_OMS_Order_Enum_OrderType'
- type: 'null'
default: null
required: false
description: Filter by order type (see OrderType enum); omit to return all types.
- in: query
name: updatedAtStart
schema:
type: string
format: date-time
default: null
required: false
description: Lower bound (inclusive) on updated_at as an ISO 8601 timestamp; returns orders updated at or after this
time.
example: '2025-07-24 14:53:00'
- in: query
name: updatedAtEnd
schema:
type: string
format: date-time
default: null
required: false
description: Upper bound (inclusive) on updated_at as an ISO 8601 timestamp; returns orders updated at or before this
time.
example: '2025-07-24 14:53:00'
- in: query
name: shippedAtStart
schema:
type: string
format: date-time
default: null
required: false
description: Lower bound (inclusive) on shipped_at as an ISO 8601 timestamp; returns orders shipped at or after this
time.
example: '2025-07-24 14:53:00'
- in: query
name: shippedAtEnd
schema:
type: string
format: date-time
default: null
required: false
description: Upper bound (inclusive) on shipped_at as an ISO 8601 timestamp; returns orders shipped at or before this
time.
example: '2025-07-24 14:53:00'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: integer
data:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderList_PublicApiOrderListOutput'
required:
- status
- data
tags:
- Orders
security:
- api_key_header_Api-Key: []
description: 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.
summary: Retrieve List of Orders
/v1/integrations/sandbox/complete-order:
post:
operationId: post-v1-integrations-sandbox-complete-order
parameters: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: integer
required:
- status
tags:
- Orders
security:
- api_key_header_Api-Key: []
description: '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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Input_CompleteOrderInput'
summary: Complete Order
/v1/integrations/submit-order:
post:
operationId: post-v1-integrations-submit-order
parameters: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: integer
required:
- status
tags:
- Orders
security:
- api_key_header_Api-Key: []
description: '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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Input_SubmitOrderIntoQueueForFulfillmentAtDateInput'
summary: Submit Order
components:
schemas:
Fulfillment_AccountApiBundle_Input_Order_CreateUpdateFulfillmentRequirements_SpecialRequirementsDatesInput:
type: object
properties:
earliest:
type:
- string
- 'null'
format: date
default: null
requested:
type:
- string
- 'null'
format: date
default: null
latest:
type:
- string
- 'null'
format: date
default: null
required: []
title: Special Requirements Dates Input
Fulfillment_AccountApiBundle_Input_Order_OrderReferenceInput:
type: object
properties:
type:
$ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderReferenceType'
value:
type: string
pattern: \S
required:
- type
- value
title: Order Reference Input
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_Enum_PublicApiOrderStatus:
type:
- string
enum:
- unfulfilled
- fulfilled
- onHold
- cancelled
title: Order Status
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_OrderPackedItemOutput:
type: object
properties:
sku:
description: Stock-keeping unit (SKU) of the order item that was packed.
type: string
line_key:
description: Identifier of the order line this packed item refers to; null when the packed item is not tied to a
specific line.
type:
- string
- 'null'
quantity:
description: Number of units of this SKU packed in this package.
type: integer
required:
- sku
- line_key
- quantity
title: Order Packed Item Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PackingGroupOutput:
type: object
properties:
key:
description: Stable identifier of the packing group, unique within the order.
type: string
name:
description: Human-readable name of the packing group; null if unnamed.
type:
- string
- 'null'
required:
- key
- name
title: Packing Group Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountForTradingPartnerOutput:
type: object
properties:
id:
description: Internal numeric identifier of the merchant account.
type: integer
name:
description: Display name of the merchant account.
type: string
required:
- id
- name
title: Account For Trading Partner Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountTradingPartnerOutput:
type: object
properties:
id:
description: Internal numeric identifier of the trading partner.
type: integer
identifier:
description: Short human-readable code identifying the trading partner.
type: string
name:
description: Display name of the trading partner.
type: string
account:
description: Merchant account that owns this trading partner relationship.
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountForTradingPartnerOutput'
required:
- id
- identifier
- name
- account
title: Account Trading Partner Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiCountryDetailOutput:
type: object
properties:
code:
description: ISO 3166-1 alpha-2 country code; null if unknown.
type:
- string
- 'null'
name:
description: Country name in English; null if unknown.
type:
- string
- 'null'
required:
- code
- name
title: Country Detail Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiExtraDataOutput:
type: object
properties:
label:
description: 'Identifier of the extra data type. Currently supported: carrierShippingMethod.'
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Enum_ShipmentNotificationExtraDataType'
value:
description: Value corresponding to the label of the extra data entry.
type: string
required:
- label
- value
title: Extra Data Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderActionsRequiredOutput:
type: object
properties:
item_mapping:
description: True if one or more order items could not be mapped to a known product and require manual mapping.
type: boolean
address:
description: True if the shipping address could not be validated and requires correction.
type: boolean
shipping_mapping:
description: True if the requested shipping service could not be mapped to an available carrier service and requires
manual mapping.
type: boolean
customs:
description: True if customs information (e.g. declared value, HS codes) is missing or incomplete for an international
shipment.
type: boolean
at_risk:
description: True if the order is at risk of missing its required ship-by date.
type: boolean
routing:
description: True if a B2B routing instruction is missing and must be supplied before shipping.
type: boolean
freight_quote:
description: True if a freight quote must be selected before the order can ship.
type: boolean
freight_info:
description: True if additional freight details (e.g. dimensions, pallet count) are required to obtain a freight
quote.
type: boolean
ship_short:
description: True if the order is flagged as a short ship, meaning one or more items could not be fulfilled in the
requested quantity.
type: boolean
hs_code:
description: True if Harmonized System (HS) tariff codes are missing for one or more items on a customs-bound shipment.
type: boolean
global_e_label:
description: True if a Global-e label (cross-border shipping label provided by the Global-e service) is still required
for the order.
type: boolean
ship_monk_hazmat_carrier_service_not_available:
description: 'Deprecated: Will always be false, kept for backwards compatibility True if the order contains hazardous
materials but no carrier service is available to ship them from the assigned warehouse.'
deprecated: true
type: boolean
automation_rule:
description: True if an automation rule has flagged the order for manual review or action.
type: boolean
pending_b2b_routing:
description: True if the order is awaiting B2B retailer routing instructions before fulfillment can proceed.
type: boolean
value_added_service_problem:
description: True if one of the order's value-added services (e.g. kitting, custom packaging) cannot be performed
and needs attention.
type: boolean
required:
- item_mapping
- address
- shipping_mapping
- customs
- at_risk
- routing
- freight_quote
- freight_info
- ship_short
- hs_code
- global_e_label
- ship_monk_hazmat_carrier_service_not_available
- automation_rule
- pending_b2b_routing
- value_added_service_problem
title: Order Actions Required Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderAttributeOutput:
type: object
properties:
name:
description: Key of the custom attribute.
type: string
value:
description: Value of the custom attribute.
type: string
required:
- name
- value
title: Order Attribute Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderCostsOutput:
type: object
properties:
estimated_shipping_related_charges:
description: Estimated shipping-related charges for the order. Null when no estimate is available.
anyOf:
- $ref: '#/components/schemas/ShipMonk_Money_Output_MoneyOutput'
- type: 'null'
estimated_packaging_material_charges:
description: Estimated charges for packaging materials used in the order. Null when no estimate is available.
anyOf:
- $ref: '#/components/schemas/ShipMonk_Money_Output_MoneyOutput'
- type: 'null'
estimated_pick_and_pack_charges:
description: Estimated charges for picking and packing labor for the order. Null when no estimate is available.
anyOf:
- $ref: '#/components/schemas/ShipMonk_Money_Output_MoneyOutput'
- type: 'null'
required:
- estimated_shipping_related_charges
- estimated_packaging_material_charges
- estimated_pick_and_pack_charges
title: Order Costs Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailCustomDataOutput:
type: object
properties:
name:
description: Key name of the custom data entry.
type: string
value:
description: Value of the custom data entry.
type: string
required:
- name
- value
title: Order Detail Custom Data Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailOutput:
type: object
properties:
order_key:
description: Unique identifier from an external system used to associate an order. Must be unique per order and
store.
type: string
order_number:
description: Customer-facing identifier for an order. Uniqueness is recommended but not strictly enforced.
type: string
order_type:
description: Order classification (e.g. standard, wholesale, return). Null when not categorized.
anyOf:
- $ref: '#/components/schemas/ShipMonk_OMS_Order_Enum_OrderType'
- type: 'null'
store:
description: Sales channel or storefront the order originated from.
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiStoreNameOutput'
warehouse:
description: Warehouse where the order is processed. Null if a warehouse has not yet been assigned.
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiWarehouseDetailOutput'
- type: 'null'
trading_partner:
description: B2B trading partner (e.g. retailer or distributor) the order is destined for. Null for direct-to-consumer
orders.
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiAccountTradingPartnerOutput'
- type: 'null'
ordered_at:
description: ISO 8601 timestamp indicating when the order was originally placed.
type: string
format: date-time
customer_email:
description: Customer's email address. Null when not provided by the source system.
anyOf:
- type: string
- type: 'null'
shipping_method:
description: Carrier and service selected to ship the order. Null if no method has been resolved yet.
anyOf:
- $ref: '#/components/schemas/Fulfillment_PublicApiBundle_ApiResource_ShippingMethod_PublicApiShippingMethodDetailOutput'
- type: 'null'
requested_shipping_service:
description: Free-text shipping service originally requested by the customer or source system; null if none was
specified.
type:
- string
- 'null'
shipping_paid:
description: Amount the customer paid for shipping, expressed in the order's currency_code.
type: number
format: double
tax_paid:
description: Amount the customer paid in taxes, expressed in the order's currency_code.
type: number
format: double
order_costs:
description: Estimated fulfillment-service charges (shipping, packaging, pick & pack) for the order. These are estimates
and may differ from final billed amounts.
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderCostsOutput'
ship_from:
description: Origin address from which the order will ship. Null when not yet determined.
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingOrderDetailAddressOutput'
- type: 'null'
ship_to:
description: Destination address the order will be shipped to. Null when not yet specified.
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiShippingOrderDetailAddressOutput'
- type: 'null'
order_status:
description: 'High-level order state: unfulfilled (not yet shipped), fulfilled (shipped), onHold (paused), cancelled.'
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_Enum_PublicApiOrderStatus'
processing_status:
description: 'Fine-grained processing stage of the order. Values: backorder, unable_to_submit, queued_to_submit,
subscription, package_forwarding, awaiting_label_request_from_merchant_facility, on_hold, submitted, pick_in_progress,
pack_in_progress, packed, awaiting_pick_up, awaiting_carrier_processing, en_route, delivered, undeliverable, shipped_untrackable,
fulfilled_by_3rd, cancellation_requested, cancelled, updating.'
$ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderListStatus'
items:
description: Line items (SKUs and quantities) included in the order.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderItemOutput'
attributes:
description: Custom key/value attributes attached to the order by the merchant or source system.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderAttributeOutput'
currency_code:
description: ISO 4217 currency code used for all monetary values on the order.
type: string
references:
description: Additional external reference identifiers attached to the order (e.g. PO number, marketplace reference).
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderReferenceOutput'
custom_data:
description: Custom key-value data associated with the order.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderDetailCustomDataOutput'
special_requirements:
description: Special handling requirements for the order, such as required documents, label dates, and pack list
rules. Null when none apply.
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSpecialRequirementsOutput'
- type: 'null'
actions_required:
description: Boolean flags indicating issues that must be resolved before the order can be fulfilled.
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderActionsRequiredOutput'
master_tracking_number:
description: Master tracking number that groups all packages of a multi-piece shipment; null when not applicable.
type:
- string
- 'null'
tracking_url:
description: Carrier URL where the customer can track the shipment; null if not yet available.
type:
- string
- 'null'
returns:
description: Return Merchandise Authorizations (RMAs) created for this order.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shipmonk/refs/heads/main/openapi/shipmonk-orders-openapi.yml