---
updatedAt: 2025-11-11T23:06:16.000Z
agentTools:
  projectIndex: https://developers.shipup.co/llms.txt
---

# Create or update single orders

## POST /v2/orders

Orders can be created or updated via a POST method to `https://api.shipup.co/v2/orders`, which accepts a JSON object describing the order. This payload also includes the order's fulfillments, line items, and trackers through nested fields.

If you use this endpoint to start sending order information, you must keep using this endpoint to send the subsequent order information as the order fulfillment and shipment progress. For example, do not use the <code>POST /v1/trackers</code> endpoint to add a tracker to your order. You must instead send a new order payload including the tracker using the <code>POST /v2/orders</code> endpoint

Orders, fulfillments, and line items not found via <code>merchant\_id</code> will be created, and those that are found will be updated. Trackers not found via <code>tracking\_number</code> will be created, and those that are found will be updated.

To understand how to adapt all your use cases to the Shipup data model and how to send them via API, please refer to Shipup's [tutorials](https://developers.shipup.co/docs/api-ftp-send-an-order).

## Request payload:

The root object which be an [order](https://developers.shipup.co/reference/order-object)

```json valid payload
{
  "merchant_id": "O_MER_TEST5",
  "order_number": "O_N_TEST5",
  "fulfillments": [
    {
      "merchant_id": "MY_FULFILLMENT_ID",
      "shipping_address": {
        "address1": "123 road street",
        "city": "City",
        "zip": "12345",
        "country": "Country"
      },
      "warehouse_merchant_id": "location_1",
      "trackers": [
        {
          "tracking_number": "1231121212",
          "line_items": [
            {
              "merchant_id": "MY_SHIPPED_PRODUCT_ID_1",
              "description": "Product Description",
              "title": "Product name"
            }
          ]
        },
        {
          "tracking_number": "12341121212",
          "line_items": [
            {
              "merchant_id": "MY_SHIPPED_PRODUCT_ID_2",
              "title": "Product name 2",
              "variant_title": "Product variant name (Blue)"
            }
          ]
        }
      ],
      "line_items": [
        {
          "merchant_id": "MY_UNSHIPPED_PRODUCT_ID"
        }
      ]
    }
  ],
  "order_details": {
    "currency_code": "EUR",
    "total_order_price_excl_tax_amount": "41.67",
    "total_order_price_incl_tax_amount": "50.00"
  }
}
```
```json response
// status
201
```

```json invalid payload
// ⚠️ This payload is invalid.
// Do not use it as an example

{
  "merchant_id": "O_MER_TEST5",
  "order_number": "O_N_TEST5",
  "fulfillments": [
    {
      "merchant_id": "MY_FULFILLMENT_ID",
      "shipping_address": {
        "address1": "123 road street",
        "city": "City",
        "zip": "12345",
        "country": {}
      },
      "trackers": [
        {
          "tracking_number": "1231121212",
          "line_items": [
            {
              "merchant_id": "MY_SHIPPED_PRODUCT_ID_1",
              "description": "Product Description",
              "title": "Product name"
            }
          ]
        },
        {
          "tracking_number": true,
          "line_items": [
            {
              "title": "Product name 2",
              "variant_title": "Product variant name (Blue)"
            }
          ]
        }
      ],
      "line_items": [
        {
          "merchant_id": "MY_UNSHIPPED_PRODUCT_ID",
          "canceled": "true"
        }
      ]
    }
  ]
}
```
```json response
// status
400

// body
{
  "errors": {
    "fulfillments": {
      "0": {
        "country": "Wrong data type: given, Hash ({}) expected: String",
        "trackers": {
          "1": {
            "tracking_number": "Wrong data type: given, TrueClass (true) expected: String or Numeric",
            "line_items": {
              "0": {
                "merchant_id": "Required"
              }
            }
          }
        },
        "line_items": {
          "0": {
            "canceled": "Wrong data type: given, String (true) expected: TrueClass or FalseClass"
          }
        }
      }
    }
  }
}
```