Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Shipmonk Orders API
version: v1.024
description: 'Operations tagged Orders across 2 of this provider''s published API definitions: shipmonk-openapi.json, shipmonk-orders-openapi.yml. Each path carries the servers of the definition it was published in.'
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
description: ''
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
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.'
/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
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.'
/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
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.'
/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
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.'
/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
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.'
components:
schemas:
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackageCartonLabelOutput:
type: object
properties:
type:
description: Kind of label printed on the carton. Values include order- and carton-level pack lists, retailer packing slips, carton/pallet labels, GS1 labels, and customized or special-instruction labels.
$ref: '#/components/schemas/ShipMonk_OMS_RequiredLabels_Enum_PackingLabelType'
identifier:
description: Identifier printed on the label (e.g. SSCC); null if the label type has no identifier.
type:
- string
- 'null'
required:
- type
- identifier
title: Package Carton Label Output
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartOutput:
type: object
properties:
main_order:
description: Reference to the original (main) order from which this order was split.
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartMainOrderOutput'
required:
- main_order
title: Order Part Output
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
ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderAdditionalDocumentInput:
type: object
properties:
name:
description: Human-readable name of the document, shown in reports and to warehouse staff.
type: string
maxLength: 255
url:
description: Publicly accessible URL of the PDF document to print and enclose with the shipment.
type: string
maxLength: 2048
required:
- name
- url
title: Create Or Update Order Additional Document Input
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPackageDataOutput:
type: object
properties:
number:
description: Sequential index (1-based) of this package within the order; null if not assigned.
type:
- integer
- 'null'
tracking_number:
description: Carrier tracking number for this package; null if not yet generated or untrackable.
type:
- string
- 'null'
tracking_url:
description: Carrier URL for tracking this package; null if not yet available.
type:
- string
- 'null'
weight_lb:
description: Total weight of the package (the unit, despite the field name, is provided in the value object); null if not measured.
anyOf:
- $ref: '#/components/schemas/ShipMonk_Measurement_Output_WeightOutput'
- type: 'null'
pallet_weight_lb:
description: Weight of the pallet on which this package is shipped (unit given inside the value object); null if not palletized or not measured.
anyOf:
- $ref: '#/components/schemas/ShipMonk_Measurement_Output_WeightOutput'
- type: 'null'
pallet_number:
description: Index (1-based) of the pallet that contains this package; null if not palletized.
type:
- integer
- 'null'
box_number:
description: Index (1-based) of the box within its pallet; null if not palletized.
type:
- integer
- 'null'
carton_labels:
description: Carton-level labels (e.g. packing slip, pallet label) applied to this package.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackageCartonLabelOutput'
packed_products:
description: Products contained in this package, aggregated by SKU with packed quantities and lot details.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiPackedProductOutput'
packing_group:
description: Packing group this package belongs to, used to split an order across multiple shipments; null if not grouped.
anyOf:
- $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PackingGroupOutput'
- type: 'null'
packed_items:
description: Order line items packed in this package, with per-line quantities.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_OrderPackedItemOutput'
required:
- number
- tracking_number
- tracking_url
- weight_lb
- pallet_weight_lb
- pallet_number
- box_number
- carton_labels
- packed_products
- packing_group
- packed_items
title: Order Package Data Output
ShipMonk_Measurement_ValueObject_WeightUnit:
type:
- string
enum:
- kg
- g
- lb
- oz
title: Weight Unit
ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemB2BAttributeInput:
type: object
properties:
name:
description: Name (key) of the B2B attribute; should be unique within the item's b2b_attributes list.
type: string
maxLength: 255
value:
description: Value of the B2B attribute identified by the sibling `name` (free-form string).
type: string
maxLength: 255
required:
- name
- value
title: Create Or Update Order Item B2 B Attribute Input
ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderShippingLabelInput:
type: object
properties:
url:
description: Publicly accessible URL pointing to the pre-generated shipping label PDF or PNG.
type: string
maxLength: 2048
required:
- url
title: Create Or Update Order Shipping Label Input
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderReferenceOutput:
type: object
properties:
type:
description: 'Type of order reference. One of: order_number, original_imported_order_number, customer_order_number, po_number, reference_number, b2b_routing_reference, release_number, job_number, depositor_order_number.'
$ref: '#/components/schemas/Fulfillment_OrderBundle_Enum_OrderReferenceType'
value:
description: The reference identifier value, interpreted according to type.
type: string
required:
- type
- value
title: Order Reference 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
ShipMonk_PublicApi_Order_OrderCreateOrUpdate_CreateOrUpdateOrderItemPackingGroupInput:
type: object
properties:
key:
description: Stable key identifying the packing group; items with the same key are packed together.
type: string
maxLength: 255
name:
description: Optional human-readable name for the packing group, shown to warehouse staff.
type:
- string
- 'null'
maxLength: 255
default: null
required:
- key
title: Create Or Update Order Item Packing Group Input
Fulfillment_PublicApiBundle_ApiResource_Carrier_PublicApiCarrierDetailOutput:
type: object
properties:
id:
type: integer
name:
type: string
required:
- id
- name
title: Carrier Detail Output
Fulfillment_PublicApiBundle_ApiResource_Order_PublicApiOrderTaxIdOutput:
type: object
properties:
tax_id_type:
description: 'Type of tax identifier. One of: VAT, IOSS, TIN, EIN, EORI, ARN, RFC, CPF, CNPJ, PCCC.'
$ref: '#/components/schemas/Fulfillment_UserBundle_Enum_TaxIdType'
value:
description: Tax identification number, formatted according to its type and issuing country.
type: string
issuing_country:
description: Country that issued the tax identification number.
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiCountryDetailOutput'
required:
- tax_id_type
- value
- issuing_country
title: Order Tax Id Output
Fulfillment_IntegrationsBundle_Input_CompleteOrderInput:
type: object
properties:
order_key:
description: Unique identifier of the order in the external (caller's) system, as originally supplied when the order was created.
type: string
example: 327b5abd-017a-4504-a50d-54f1cea80269
store_id:
description: Identifier of the store this return belongs to.
type: integer
example: 123456
pack_type:
description: 'Optional packaging type for the simulated fulfillment: ''singlepack'' (all items in one box) or ''multipack'' (items split across multiple boxes).'
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Enum_SandboxPackType'
default: singlepack
required:
- order_key
- store_id
title: Complete Order 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_PublicApiOrderPartMainOrderOutput:
type: object
properties:
order_number:
description: Order number of the main order this part was split from.
type: string
parts:
description: List of all part orders created from splitting the main order.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiOrderPartItemOutput'
required:
- order_number
- parts
title: Order Part Main Order Output
Fulfillment_OrderBundle_Input_Enum_OrderItemSpecialInstructionType:
type:
- string
enum:
- embroidery
title: Order Item Special Instruction Type
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_Enum_ShipmentNotificationExtraDataType:
type:
- string
enum:
- carrierShippingMethod
title: Shipment Notification Extra Data Type
Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSerialNumberOutput:
type: object
properties:
line_key:
description: Key of the order line item these serial numbers belong to; null when serial numbers cannot be matched to a specific line.
type:
- string
- 'null'
serial_numbers:
description: Serial numbers recorded for units fulfilled on this order line.
type: array
items:
$ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_Output_Order_PublicApiSerialNumberItemOutput'
required:
- line_key
- serial_numbers
title: Serial Number Output
Fulfillment_OrderBundle_Enum_OrderListStatus:
type:
- string
enum:
- 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
title: Order List Status
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
ac
# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shipmonk/refs/heads/main/openapi/shipmonk-orders-api-openapi.yml