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.