Create or Update Order

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 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.

{
  "store_id": 123456,
  "order_number": "Order-123",
  "order_key": "327b5abd-017a-4504-a50d-54f1cea80269",
  "ordered_at": "2025-07-24 14:53:00",
  "warehouse": "PA1",
  "submit_at": "2025-07-24 14:53:00"
}