# Create or update order

Create a new order or update an existing order. If the orderKey is specified, ShipStation will attempt to locate the order with that key. If found, the existing order will be updated. If not found, a new order will be created with that orderKey.

Note: This call does not currently support partial updates. The entire resource must be provided in the body of the request.

Only orders in an open status (awaiting_payment, awaiting_shipment, on_hold) can be updated. Orders in cancelled and shipped states may not be updated.

Endpoint: POST /orders/createorder
Version: 1.0.0
Security: basicAuth

## Request fields (application/json):

  - `orderNumber` (string)
    User-defined order number
    Example: "TEST-ORDER-API-DOCS"

  - `orderKey` (string)
    Unique key for the order
    Example: "0f6bec18-3e89-4771-83aa-f392d84f4c74"

  - `orderDate` (string)
    Date the order was placed
    Example: "2015-06-29T08:46:27Z"

  - `paymentDate` (any)
    Date the order was paid
    Example: "2015-06-29T08:46:27Z"

  - `shipByDate` (any)
    Date the order should be shipped by
    Example: "2015-07-05T00:00:00Z"

  - `orderStatus` (string)
    Current status of the order
    Enum: "awaiting_payment", "awaiting_shipment", "pending_fulfillment", "shipped", "on_hold", "cancelled", "rejected_fulfillment"

  - `customerUsername` (string)
    Customer username or identifier
    Example: "headhoncho@whitehouse.gov"

  - `customerEmail` (string)
    Customer email address
    Example: "headhoncho@whitehouse.gov"

  - `billTo` (object)
    Physical address for shipping or billing

  - `billTo.name` (string)
    Name of the recipient
    Example: "John Doe"

  - `billTo.company` (any)
    Company name
    Example: "Acme Corp"

  - `billTo.street1` (string)
    First line of the street address
    Example: "123 Main St"

  - `billTo.street2` (any)
    Second line of the street address
    Example: "Apt 4B"

  - `billTo.street3` (any)
    Third line of the street address
    Example: "Building B"

  - `billTo.city` (string)
    City name
    Example: "Austin"

  - `billTo.state` (string)
    State or province code
    Example: "TX"

  - `billTo.postalCode` (string)
    Postal or ZIP code
    Example: "78701"

  - `billTo.country` (string)
    Two-letter ISO country code
    Example: "US"

  - `billTo.phone` (any)
    Phone number
    Example: "512-555-1234"

  - `billTo.residential` (any)
    Whether the address is residential
    Example: true

  - `billTo.addressVerified` (any)
    Address verification status
    Example: "Address validated successfully"

  - `shipTo` (object)
    Physical address for shipping or billing

  - `items` (array)
    Array of order items

  - `items.lineItemKey` (any)
    External line item key
    Example: "vd08-MSLbtx"

  - `items.sku` (string)
    Product SKU
    Example: "ABC123"

  - `items.name` (string)
    Item name
    Example: "Test item #1"

  - `items.imageUrl` (any)
    Item image URL
    Example: "https://example.com/images/product.jpg"

  - `items.weight` (object)
    Weight measurement

  - `items.weight.value` (number, required)
    Weight value
    Example: 24

  - `items.weight.units` (string, required)
    Weight unit of measurement
    Enum: "pounds", "ounces", "grams"

  - `items.quantity` (integer)
    Quantity
    Example: 2

  - `items.unitPrice` (number)
    Unit price
    Example: 99.99

  - `items.taxAmount` (any)
    Tax amount
    Example: 2.5

  - `items.shippingAmount` (any)
    Shipping amount
    Example: 5

  - `items.warehouseLocation` (any)
    Warehouse location
    Example: "Aisle 1, Bin 7"

  - `items.options` (array)
    Item options

  - `items.options.name` (string)
    Option name
    Example: "Size"

  - `items.options.value` (string)
    Option value
    Example: "Large"

  - `items.productId` (any)
    Product ID
    Example: 7239919

  - `items.fulfillmentSku` (any)
    Fulfillment SKU
    Example: "SKU-Fulfilled"

  - `items.adjustment` (boolean)
    Whether this is an adjustment item

  - `items.upc` (any)
    UPC code
    Example: "32-65-98"

  - `amountPaid` (number)
    Amount paid by customer
    Example: 218.73

  - `taxAmount` (number)
    Total tax amount
    Example: 5

  - `customerNotes` (any)
    Notes from the customer
    Example: "Please ship as soon as possible!"

  - `internalNotes` (any)
    Internal notes (not visible to customer)
    Example: "Customer called and would like to upgrade shipping"

  - `gift` (boolean)
    Whether this is a gift order

  - `giftMessage` (any)
    Gift message
    Example: "Happy Birthday!"

  - `paymentMethod` (any)
    Payment method used
    Example: "Credit Card"

  - `requestedShippingService` (any)
    Shipping service requested by customer
    Example: "Priority Mail"

  - `carrierCode` (any)
    Carrier code
    Example: "fedex"

  - `serviceCode` (any)
    Service code
    Example: "fedex_2day"

  - `packageCode` (any)
    Package type code
    Example: "package"

  - `confirmation` (string)
    Delivery confirmation type
    Enum: "none", "delivery", "signature", "adult_signature", "direct_signature"

  - `shipDate` (any)
    Date the order was shipped
    Example: "2015-07-02"

  - `holdUntilDate` (any)
    Date to hold order until
    Example: "2015-07-05"

  - `dimensions` (any)

  - `insuranceOptions` (object)
    Shipping insurance options

  - `insuranceOptions.provider` (any)
    Insurance provider
    Enum: "none", "carrier", "shipsurance"

  - `insuranceOptions.insureShipment` (boolean)
    Whether to insure the shipment
    Example: true

  - `insuranceOptions.insuredValue` (number)
    Insured value amount
    Example: 200

  - `internationalOptions` (object)
    International shipping options

  - `internationalOptions.contents` (any)
    Type of contents
    Enum: "merchandise", "documents", "gift", "returned_goods", "sample"

  - `internationalOptions.customsItems` (array)
    Array of customs items

  - `internationalOptions.nonDelivery` (any)
    Action to take if delivery fails
    Enum: "return_to_sender", "treat_as_abandoned"

  - `advancedOptions` (object)
    Advanced shipping options

  - `advancedOptions.warehouseId` (any)
    Warehouse ID
    Example: 98765

  - `advancedOptions.nonMachinable` (boolean)
    Whether the package is non-machinable

  - `advancedOptions.saturdayDelivery` (boolean)
    Whether to deliver on Saturday

  - `advancedOptions.containsAlcohol` (boolean)
    Whether the package contains alcohol

  - `advancedOptions.mergedOrSplit` (boolean)
    Whether this is a merged or split order

  - `advancedOptions.mergedIds` (array)
    Array of merged order IDs

  - `advancedOptions.parentId` (any)
    Parent order ID for split orders
    Example: 93348442

  - `advancedOptions.storeId` (any)
    Store ID
    Example: 12345

  - `advancedOptions.customField1` (any)
    Custom field 1
    Example: "Custom data that you can add to an order"

  - `advancedOptions.customField2` (any)
    Custom field 2
    Example: "Per UI settings, this can appear on some carrier labels"

  - `advancedOptions.customField3` (any)
    Custom field 3
    Example: "https://help.shipstation.com/hc/en-us/articles/206639957"

  - `advancedOptions.source` (any)
    Order source
    Example: "Webstore"

  - `advancedOptions.billToParty` (any)
    Bill to party
    Example: "third_party"

  - `advancedOptions.billToAccount` (any)
    Bill to account
    Example: "123456789"

  - `advancedOptions.billToPostalCode` (any)
    Bill to postal code
    Example: "78701"

  - `advancedOptions.billToCountryCode` (any)
    Bill to country code
    Example: "US"

  - `tagIds` (array)
    Array of tag IDs associated with this order

## Response 200 fields (application/json):

  - `orderId` (integer)
    System-generated identifier for the order
    Example: 93348442

  - `orderNumber` (string)
    User-defined order number
    Example: "TEST-ORDER-API-DOCS"

  - `orderKey` (string)
    Unique key for the order
    Example: "0f6bec18-3e89-4771-83aa-f392d84f4c74"

  - `orderDate` (string)
    Date the order was placed
    Example: "2015-06-29T08:46:27Z"

  - `createDate` (string)
    Timestamp when order was created in ShipStation
    Example: "2016-01-12T16:03:06Z"

  - `modifyDate` (string)
    Timestamp when order was last modified
    Example: "2016-01-12T16:03:06Z"

  - `paymentDate` (any)
    Date the order was paid
    Example: "2015-06-29T08:46:27Z"

  - `shipByDate` (any)
    Date the order should be shipped by
    Example: "2015-07-05T00:00:00Z"

  - `orderStatus` (string)
    Current status of the order
    Enum: "awaiting_payment", "awaiting_shipment", "pending_fulfillment", "shipped", "on_hold", "cancelled", "rejected_fulfillment"

  - `customerId` (integer)
    Unique identifier for the customer
    Example: 37701499

  - `customerUsername` (string)
    Customer username or identifier
    Example: "headhoncho@whitehouse.gov"

  - `customerEmail` (string)
    Customer email address
    Example: "headhoncho@whitehouse.gov"

  - `billTo` (object)
    Physical address for shipping or billing

  - `billTo.name` (string)
    Name of the recipient
    Example: "John Doe"

  - `billTo.company` (any)
    Company name
    Example: "Acme Corp"

  - `billTo.street1` (string)
    First line of the street address
    Example: "123 Main St"

  - `billTo.street2` (any)
    Second line of the street address
    Example: "Apt 4B"

  - `billTo.street3` (any)
    Third line of the street address
    Example: "Building B"

  - `billTo.city` (string)
    City name
    Example: "Austin"

  - `billTo.state` (string)
    State or province code
    Example: "TX"

  - `billTo.postalCode` (string)
    Postal or ZIP code
    Example: "78701"

  - `billTo.country` (string)
    Two-letter ISO country code
    Example: "US"

  - `billTo.phone` (any)
    Phone number
    Example: "512-555-1234"

  - `billTo.residential` (any)
    Whether the address is residential
    Example: true

  - `billTo.addressVerified` (any)
    Address verification status
    Example: "Address validated successfully"

  - `shipTo` (object)
    Physical address for shipping or billing

  - `items` (array)
    Array of order items

  - `items.orderItemId` (integer)
    System-generated order item ID
    Example: 128836912

  - `items.lineItemKey` (any)
    External line item key
    Example: "vd08-MSLbtx"

  - `items.sku` (string)
    Product SKU
    Example: "ABC123"

  - `items.name` (string)
    Item name
    Example: "Test item #1"

  - `items.imageUrl` (any)
    Item image URL
    Example: "https://example.com/images/product.jpg"

  - `items.weight` (object)
    Weight measurement

  - `items.weight.value` (number, required)
    Weight value
    Example: 24

  - `items.weight.units` (string, required)
    Weight unit of measurement
    Enum: "pounds", "ounces", "grams"

  - `items.quantity` (integer)
    Quantity
    Example: 2

  - `items.unitPrice` (number)
    Unit price
    Example: 99.99

  - `items.taxAmount` (any)
    Tax amount
    Example: 2.5

  - `items.shippingAmount` (any)
    Shipping amount
    Example: 5

  - `items.warehouseLocation` (any)
    Warehouse location
    Example: "Aisle 1, Bin 7"

  - `items.options` (array)
    Item options

  - `items.options.name` (string)
    Option name
    Example: "Size"

  - `items.options.value` (string)
    Option value
    Example: "Large"

  - `items.productId` (any)
    Product ID
    Example: 7239919

  - `items.fulfillmentSku` (any)
    Fulfillment SKU
    Example: "SKU-Fulfilled"

  - `items.adjustment` (boolean)
    Whether this is an adjustment item

  - `items.upc` (any)
    UPC code
    Example: "32-65-98"

  - `items.createDate` (string)
    Creation timestamp

  - `items.modifyDate` (string)
    Last modification timestamp

  - `orderTotal` (number)
    Total order amount
    Example: 194.43

  - `amountPaid` (number)
    Amount paid by customer
    Example: 218.73

  - `taxAmount` (number)
    Total tax amount
    Example: 5

  - `customerNotes` (any)
    Notes from the customer
    Example: "Please ship as soon as possible!"

  - `internalNotes` (any)
    Internal notes (not visible to customer)
    Example: "Customer called and would like to upgrade shipping"

  - `gift` (boolean)
    Whether this is a gift order

  - `giftMessage` (any)
    Gift message
    Example: "Happy Birthday!"

  - `paymentMethod` (any)
    Payment method used
    Example: "Credit Card"

  - `requestedShippingService` (any)
    Shipping service requested by customer
    Example: "Priority Mail"

  - `carrierCode` (any)
    Carrier code
    Example: "fedex"

  - `serviceCode` (any)
    Service code
    Example: "fedex_2day"

  - `packageCode` (any)
    Package type code
    Example: "package"

  - `confirmation` (string)
    Delivery confirmation type
    Enum: "none", "delivery", "signature", "adult_signature", "direct_signature"

  - `shipDate` (any)
    Date the order was shipped
    Example: "2015-07-02"

  - `holdUntilDate` (any)
    Date to hold order until
    Example: "2015-07-05"

  - `dimensions` (any)

  - `insuranceOptions` (object)
    Shipping insurance options

  - `insuranceOptions.provider` (any)
    Insurance provider
    Enum: "none", "carrier", "shipsurance"

  - `insuranceOptions.insureShipment` (boolean)
    Whether to insure the shipment
    Example: true

  - `insuranceOptions.insuredValue` (number)
    Insured value amount
    Example: 200

  - `internationalOptions` (object)
    International shipping options

  - `internationalOptions.contents` (any)
    Type of contents
    Enum: "merchandise", "documents", "gift", "returned_goods", "sample"

  - `internationalOptions.customsItems` (array)
    Array of customs items

  - `internationalOptions.nonDelivery` (any)
    Action to take if delivery fails
    Enum: "return_to_sender", "treat_as_abandoned"

  - `advancedOptions` (object)
    Advanced shipping options

  - `advancedOptions.warehouseId` (any)
    Warehouse ID
    Example: 98765

  - `advancedOptions.nonMachinable` (boolean)
    Whether the package is non-machinable

  - `advancedOptions.saturdayDelivery` (boolean)
    Whether to deliver on Saturday

  - `advancedOptions.containsAlcohol` (boolean)
    Whether the package contains alcohol

  - `advancedOptions.mergedOrSplit` (boolean)
    Whether this is a merged or split order

  - `advancedOptions.mergedIds` (array)
    Array of merged order IDs

  - `advancedOptions.parentId` (any)
    Parent order ID for split orders
    Example: 93348442

  - `advancedOptions.storeId` (any)
    Store ID
    Example: 12345

  - `advancedOptions.customField1` (any)
    Custom field 1
    Example: "Custom data that you can add to an order"

  - `advancedOptions.customField2` (any)
    Custom field 2
    Example: "Per UI settings, this can appear on some carrier labels"

  - `advancedOptions.customField3` (any)
    Custom field 3
    Example: "https://help.shipstation.com/hc/en-us/articles/206639957"

  - `advancedOptions.source` (any)
    Order source
    Example: "Webstore"

  - `advancedOptions.billToParty` (any)
    Bill to party
    Example: "third_party"

  - `advancedOptions.billToAccount` (any)
    Bill to account
    Example: "123456789"

  - `advancedOptions.billToPostalCode` (any)
    Bill to postal code
    Example: "78701"

  - `advancedOptions.billToCountryCode` (any)
    Bill to country code
    Example: "US"

  - `tagIds` (array)
    Array of tag IDs associated with this order

  - `userId` (any)
    User assigned to order (GUID format)
    Example: "123456AB-ab12-3c4d-5e67-89f1abc1defa"

  - `externallyFulfilled` (boolean)
    Whether order is externally fulfilled

  - `externallyFulfilledBy` (any)
    External fulfillment provider name
    Example: "Amazon FBA"

## Response 400 fields (application/json):

  - `message` (string)
    Example: "Invalid request parameters"

## Response 401 fields (application/json):

  - `message` (string)
    Example: "Invalid API credentials"

## Response 500 fields (application/json):

  - `message` (string)
    Example: "An internal error occurred"