Create/Update Order

You can use this method to create a new order or update an existing order. If the orderKey is specified, ShipStation will attempt to locate the order with the specified orderKey. If found, the existing order with that key will be updated. If the orderKey is not found, a new order will be created with that orderKey.

For split orders, see the mergedOrSplit property in Advanced Options. This property (key) is always required for merged or split orders.

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

NOTE Only orders in an open status in ShipStation (awaiting_payment,awaiting_shipment, and on_hold) can be updated through this method. Orders in the cancelled and shipped states may not be updated. The body of this request should specify an Order object:

Name Data Type Description
orderId number A unique ID assigned with the order by ShipStation API V1. This value will be returned in the response whenever you create a new order.
Optional

Notes about using this property:
  • Do not include this property when creating a new order.
  • Including the orderID property when updating the order will help prevent duplicate order records.
  • When updating split orders, you must always include this property.
orderNumber string A user-defined order number used to identify an order.
Required, max-length: 50
orderKey string A user-provided key that should be unique to each order.
Optional

If an orderKey is not provided, ShipStation will create a new order and generate a unique orderKey for that order.

If the orderKey is provided, the createorder method will either:
create a new order if the provided orderKey is not found, or,
update the existing order if the orderKey is found.

NOTE: * This property is always required when updating a split order.
orderDate string The date the order was placed.
Required
paymentDate string The date the order was paid for.
Optional
shipByDate string The date the order is to be shipped before or on.
Optional
This field is a suggested value generated by the order source/platform/cart and passed to ShipStation.
orderStatus string The order's status.
Required
Possible values: awaiting_payment, awaiting_shipment, shipped, on_hold, cancelled, pending_fulfillment
customerUsername string The customer's username.
Optional*
NOTE: This property needs to be defined to generate a customer profile.
customerEmail string The customer's email address.
Optional
billTo Object: Array of strings and boolean The recipient's billing address.
Required Use the Address model.
shipTo Object: Array of strings and boolean The recipient's shipping address.
Required Use the Address model.
items Array of item objects Use an array of OrderItem models.
Optional
amountPaid number The total amount paid for the Order.
Optional
taxAmount number The total tax amount for the Order.
Optional
shippingAmount number Shipping amount paid by the customer, if any.
Optional
customerNotes string Notes left by the customer when placing the order.
Optional
internalNotes string Private notes that are only visible to the seller.
Optional
gift boolean Specifies whether or not this Order is a gift.
Optional
giftMessage string Gift message left by the customer when placing the order.
Optional
paymentMethod string Method of payment used by the customer.
Optional
requestedShippingService string Identifies the shipping service the customer selected when placing this order.
This value is given to ShipStation by the marketplace/cart and helps to identify what shipping service the customer selected upon checkout.
Optional
carrierCode string The code for the carrier that is to be used (or was used) when this order is shipped (was shipped).
Optional
serviceCode string The code for the shipping service that is to be used (or was used) when this order is shipped (was shipped).
Optional
packageCode string The code for the package type that is to be used (or was used) when this order is shipped (was shipped).
Optional
confirmation string The type of delivery confirmation that is to be used (or was used) when this order is shipped (was shipped).
Possible values: none, delivery, signature, adult_signature, and direct_signature. Note: direct_signature is available for FedEx only.
Optional
shipDate string The date the order was shipped.
Optional
weight Object: numbers and strings Weight of the order.
Use the Weight model.
Optional
dimensions Object: numbers and strings Dimensions of the order.
Use the Dimensions model.
Optional
insuranceOptions Object: numbers, strings, and boolean The shipping insurance information associated with this order.
Use the InsuranceOptions model.
Optional
internationalOptions Object: strings, and an array of customs items Customs information that can be used to generate customs documents for international orders.
Use the InternationalOptions model.
Optional
customsCountryCode string The default two-letter ISO Origin Country code for the Product.
advancedOptions Object: numbers, strings, and boolean Various advanced options may be available depending on the shipping carrier that is used to ship the order.
Use the AdvancedOptions model.
Optional
tagIds Array of numbers

or Null		 Array of tagIds.
Each tagId identifies a tag that has been associated with this order.
Optional

Example Request

POST /orders/createorder HTTP/1.1
Host: ssapi.shipstation.com
Authorization: __YOUR_AUTH_HERE__
Content-Type: application/json

{
  "orderNumber": "TEST-ORDER-API-DOCS",
  "orderKey": "0f6bec18-3e89-4881-83aa-f392d84f4c74",
  "orderDate": "2015-06-29T08:46:27.0000000",
  "paymentDate": "2015-06-29T08:46:27.0000000",
  "shipByDate": "2015-07-05T00:00:00.0000000",
  "orderStatus": "awaiting_shipment",
  "customerId": 37701499,
  "customerUsername": "[email protected]",
  "customerEmail": "[email protected]",
  "billTo": {
    "name": "The President",
    "company": null,
    "street1": null,
    "street2": null,
    "street3": null,
    "city": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "phone": null,
    "residential": null
  },
  "shipTo": {
    "name": "The President",
    "company": "US Govt",
    "street1": "1600 Pennsylvania Ave",
    "street2": "Oval Office",
    "street3": null,
    "city": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "country": "US",
    "phone": "555-555-5555",
    "residential": true
  },
  "items": [
    {
      "lineItemKey": "vd08-MSLbtx",
      "sku": "ABC123",
      "name": "Test item #1",
      "imageUrl": null,
      "weight": {
        "value": 24,
        "units": "ounces"
      },
      "quantity": 2,
      "unitPrice": 99.99,
      "taxAmount": 2.5,
      "shippingAmount": 5,
      "warehouseLocation": "Aisle 1, Bin 7",
      "options": [
        {
          "name": "Size",
          "value": "Large"
        }
      ],
      "productId": 123456,
      "fulfillmentSku": null,
      "adjustment": false,
      "upc": "32-65-98"
    },
    {
      "lineItemKey": null,
      "sku": "DISCOUNT CODE",
      "name": "10% OFF",
      "imageUrl": null,
      "weight": {
        "value": 0,
        "units": "ounces"
      },
      "quantity": 1,
      "unitPrice": -20.55,
      "taxAmount": null,
      "shippingAmount": null,
      "warehouseLocation": null,
      "options": [],
      "productId": 123456,
      "fulfillmentSku": "SKU-Discount",
      "adjustment": true,
      "upc": null
    }
  ],
  "amountPaid": 218.73,
  "taxAmount": 5,
  "shippingAmount": 10,
  "customerNotes": "Please ship as soon as possible!",
  "internalNotes": "Customer called and would like to upgrade shipping",
  "gift": true,
  "giftMessage": "Thank you!",
  "paymentMethod": "Credit Card",
  "requestedShippingService": "Priority Mail",
  "carrierCode": "fedex",
  "serviceCode": "fedex_2day",
  "packageCode": "package",
  "confirmation": "delivery",
  "shipDate": "2015-07-02",
  "weight": {
    "value": 25,
    "units": "ounces"
  },
  "dimensions": {
    "units": "inches",
    "length": 7,
    "width": 5,
    "height": 6
  },
  "insuranceOptions": {
    "provider": "carrier",
    "insureShipment": true,
    "insuredValue": 200
  },
  "internationalOptions": {
    "contents": null,
    "customsItems": null
  },
  "advancedOptions": {
    "warehouseId": null,
    "nonMachinable": false,
    "saturdayDelivery": false,
    "containsAlcohol": false,
    "mergedOrSplit": false,
    "mergedIds": [],
    "parentId": null,
    "storeId": null,
    "customField1": "Custom data that you can add to an order. See Custom Field #2 & #3 for more info!",
    "customField2": "Per UI settings, this information can appear on some carrier's shipping labels. See link below",
    "customField3": "https://help.shipstation.com/hc/en-us/articles/206639957",
    "source": "Webstore",
    "billToParty": null,
    "billToAccount": null,
    "billToPostalCode": null,
    "billToCountryCode": null
  },
  "tagIds": [
    53974
  ]
}

Example Response

{
  "orderId": 140335319,
  "orderNumber": "TEST-ORDER-API-DOCS",
  "orderKey": "0f6bec18-3e89-4881-83aa-f392d84f4c74",
  "orderDate": "2015-06-29T08:46:27.0000000",
  "createDate": "2016-02-16T15:16:53.7070000",
  "modifyDate": "2016-02-16T15:16:53.7070000",
  "paymentDate": "2015-06-29T08:46:27.0000000",
  "shipByDate": "2015-07-05T00:00:00.0000000",
  "orderStatus": "awaiting_shipment",
  "customerId": null,
  "customerUsername": "[email protected]",
  "customerEmail": "[email protected]",
  "billTo": {
    "name": "The President",
    "company": null,
    "street1": null,
    "street2": null,
    "street3": null,
    "city": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "phone": null,
    "residential": null,
    "addressVerified": null
  },
  "shipTo": {
    "name": "The President",
    "company": "US Govt",
    "street1": "1600 Pennsylvania Ave",
    "street2": "Oval Office",
    "street3": null,
    "city": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "country": "US",
    "phone": "555-555-5555",
    "residential": false,
    "addressVerified": "Address validation warning"
  },
  "items": [
    {
      "orderItemId": 192210956,
      "lineItemKey": "vd08-MSLbtx",
      "sku": "ABC123",
      "name": "Test item #1",
      "imageUrl": null,
      "weight": {
        "value": 24,
        "units": "ounces"
      },
      "quantity": 2,
      "unitPrice": 99.99,
      "taxAmount": 2.5,
      "shippingAmount": 5,
      "warehouseLocation": "Aisle 1, Bin 7",
      "options": [
        {
          "name": "Size",
          "value": "Large"
        }
      ],
      "productId": null,
      "fulfillmentSku": null,
      "adjustment": false,
      "upc": "32-65-98",
      "createDate": "2016-02-16T15:16:53.707",
      "modifyDate": "2016-02-16T15:16:53.707"
    },
    {
      "orderItemId": 192210957,
      "lineItemKey": null,
      "sku": "DISCOUNT CODE",
      "name": "10% OFF",
      "imageUrl": null,
      "weight": {
        "value": 0,
        "units": "ounces"
      },
      "quantity": 1,
      "unitPrice": -20.55,
      "taxAmount": null,
      "shippingAmount": null,
      "warehouseLocation": null,
      "options": [],
      "productId": null,
      "fulfillmentSku": "SKU-Discount",
      "adjustment": true,
      "upc": null,
      "createDate": "2016-02-16T15:16:53.707",
      "modifyDate": "2016-02-16T15:16:53.707"
    }
  ],
  "orderTotal": 194.43,
  "amountPaid": 218.73,
  "taxAmount": 5,
  "shippingAmount": 10,
  "customerNotes": "Please ship as soon as possible!",
  "internalNotes": "Customer called and would like to upgrade shipping",
  "gift": true,
  "giftMessage": "Thank you!",
  "paymentMethod": "Credit Card",
  "requestedShippingService": "Priority Mail",
  "carrierCode": "fedex",
  "serviceCode": "fedex_2day",
  "packageCode": "package",
  "confirmation": "delivery",
  "shipDate": "2015-07-02",
  "holdUntilDate": null,
  "weight": {
    "value": 25,
    "units": "ounces"
  },
  "dimensions": {
    "units": "inches",
    "length": 7,
    "width": 5,
    "height": 6
  },
  "insuranceOptions": {
    "provider": "carrier",
    "insureShipment": true,
    "insuredValue": 200
  },
  "internationalOptions": {
    "contents": null,
    "customsItems": null,
    "nonDelivery": null
  },
  "advancedOptions": {
    "warehouseId": 9876,
    "nonMachinable": false,
    "saturdayDelivery": false,
    "containsAlcohol": false,
    "mergedOrSplit": false,
    "mergedIds": [],
    "parentId": null,
    "storeId": 12345,
    "customField1": "Custom data that you can add to an order. See Custom Field #2 & #3 for more info!",
    "customField2": "Per UI settings, this information can appear on some carrier's shipping labels. See link below",
    "customField3": "https://help.shipstation.com/hc/en-us/articles/206639957",
    "source": "Webstore",
    "billToParty": null,
    "billToAccount": null,
    "billToPostalCode": null,
    "billToCountryCode": null
  },
  "tagIds": null,
  "userId": null,
  "externallyFulfilled": false,
  "externallyFulfilledBy": null
}