Creating an Order

Overview

The ShipMonk Create Order endpoint allows you to seamlessly integrate order creation between your system and ShipMonk's fulfillment platform. The API is designed to prevent duplicate orders and automatically handle warehouse routing based on your inventory configuration.

Prerequisites

Before you begin, ensure you have:

1. ShipMonk Account: Active account with API access enabled
2. API Key: Obtain from your ShipMonk account
3. A ShipMonk API Store: It is important to note that creating orders via API should only be done using the ShipMonk API store, for more information regarding stores and setup, reference this help doc.
4. Store ID: Unique identifier for your store (obtained from ShipMonk dashboard)

Authentication

Include your API key in the request header:

curl --request GET \
     --url 'SANDBOX OR PRODUCTION URL HERE' \
     --header 'Api-Key: YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

Endpoint

A comprehensive list of endpoints can be found in the API Reference section of our documentation.

Request Body Structure

Required Fields

Order Status Options

• unfulfilled: Standard order for ShipMonk to process and ship
• cancelled: Cancel an order or create it as cancelled
• fulfilled: Mark order as fulfilled by a third party (not ShipMonk)
• onHold: Create order but place it on hold (won't be processed)

Optional Fields

Basic Example Request

Here's a minimal example to create your first order:

{
  "shipTo": {
    "name": "Name",
    "street1": "123 Fake Street",
    "state": "NY",
    "city": "New York",
    "zip": "10001",
    "countryCode": "US",
    "phone": "2122125555"
  },
  "orderStatus": "unfulfilled",
  "shippingPaymentTerms": {
    "type": "sender"
  },
  "recipientTaxId": {
    "type": "VAT"
  },
  "storeId": 123456,
  "items": [
    {
      "sku": "Test1",
      "quantity": 1
    }
  ],
  "orderNumber": "Test-Order",
  "requestedShippingService": "Standard",
  "orderKey": "Test-Order",
  "orderedAt": "2023-10-20T13:42:57+0000"
}

Example of Optional Fields

{
  "custom_data": {
    "customer_notes": "Gift wrap requested",
    "internal_reference": "REF-2024-001"
  },
  "submit_at": "2024-01-15T10:00:00Z"
}

Important Behaviors

Duplicate Prevention

The API will not create duplicate orders if you send the same store_id and order_key combination. This allows you to safely retry requests or update existing orders.

⚠️ Warning: Changing the order_key for the same order will create a duplicate. Always use the same order_key for the same order throughout its lifecycle.

Automatic Warehouse Resolution

If you don't specify a warehouse, ShipMonk automatically determines the optimal warehouse based on:

• Available inventory
• Shipping destination
• Your account configuration

Order Submission Timing

If submit_at is not provided, the order will be submitted according to your store's default settings in the ShipMonk dashboard.

International Shipments

Recipient Tax ID Requirements

For international shipments to certain countries, a recipient tax ID is mandatory:

• 🇲🇽 Mexico: Required
• 🇧🇷 Brazil: Required
• 🇰🇷 South Korea: Required

Best Practice: Collect recipient tax IDs during checkout for all international orders to avoid order holds.

If a required tax ID is missing, the order will be marked with status "Recipient Tax ID Required" and must be updated before processing.

Response Handling

Successful Response

A successful order creation will return a 200 OK status with order details.

Common Errors

Step-by-Step: Creating Your First Order

Step 1: Gather Required Information

• Store ID
• Order Number
• Order Key
• Requested Shipping Service
• Item(s)
• Ship-to Information
• Order Status
• Recipient Tax ID
• Order Date/time

Step 2: Prepare Your Request

curl --request POST \
     --url 'SANDBOX_OR_PRODUCTION_URL_HERE' \
     --header 'Api-Key: YOUR_API_KEY_HERE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "items": [
    {
      "sku": "TEST1",
      "quantity": 1
    }
  ],
  "shipTo": {
    "name": "John Doe",
    "street1": "123 Fake Street",
    "state": "FL",
    "city": "Miami",
    "zip": "10001",
    "countryCode": "US",
    "phone": "15555555"
  },
  "orderStatus": "unfulfilled",
  "shippingPaymentTerms": {
    "type": "sender"
  },
  "recipientTaxId": {
    "type": "VAT"
  },
  "storeId": 11364,
  "orderNumber": "TEST-ORDER-1",
  "requestedShippingService": "ShipMonk Standard",
  "orderKey": "UNIQUE-ORDER-KEY",
  "orderedAt": "2024-10-27T15:23:11+0000"
}
'

Step 3: Send the Request

Use your preferred HTTP client or the cURL example provided above.

Step 4: Verify the Response

Check that you receive a successful response and note the order details returned.

Step 5: Monitor in ShipMonk Dashboard

Log into your ShipMonk dashboard to verify the order appears correctly.

Updating an Existing Order

To update an order, send another request with the same store_id and order_key, but with modified fields:

{
  "store_id": 12345,
  "order_key": "ORDER-001",
  "status": "onHold"
}

This will update the existing order to "on hold" status without creating a duplicate.

Best Practices

1. Use Consistent Order Keys: Always use the same identifier from your system as the order_key
2. Handle Tax IDs Proactively: Collect recipient tax IDs during checkout for international orders
3. Implement Retry Logic: Safe to retry requests due to duplicate prevention
4. Log API Responses: Keep records of order creation for troubleshooting
5. Test in Sandbox: If available, test your integration in a sandbox environment first

Next Steps

After successfully creating your first order, explore:

• Retrieving order status and tracking information
• Updating order details
• Cancelling orders
• Bulk order creation workflows

Support

For additional help:

• 📚 ShipMonk Support Documents
• 💬 Contact ShipMonk support through ShipMonk web app dashboard