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, this key is always required.

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, optional* A unique id assigned to the order by ShipStation API. This value will be returned in the response whenever a new order is created or updated. For split orders, you must always include this property when updating an order.
orderNumber string, required, max-length: 50 A user-defined order number used to identify an order.
orderKey string, optional* A user-provided key that should be unique to each order. 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, required The date the order was placed.
paymentDate string, optional The date the order was paid for.
shipByDate string, optional The date the order is to be shipped before or on. This field is a suggested value generated by the order source/platform/cart and passed to ShipStation.
orderStatus string, required The order's status. Possible values: awaiting_payment, awaiting_shipment, shipped, on_hold, cancelled
customerUsername string, optional The customer's username. Note: This property needs to be defined in order to generate a customer profile
customerEmail string, optional The customer's email address.
billTo Address, required The recipients billing address. Use the Address model.
shipTo Address, required The recipient's shipping address. Use the Address model.
items OrderItem, optional An array of item objects. Use an array of OrderItem models.
amountPaid number, optional The total amount paid for the Order.
taxAmount number, optional The total tax amount for the Order.
shippingAmount number, optional Shipping amount paid by the customer, if any.
customerNotes string, optional Notes left by the customer when placing the order.
internalNotes string, optional Private notes that are only visible to the seller.
gift boolean, optional Specifies whether or not this Order is a gift
giftMessage string, optional Gift message left by the customer when placing the order.
paymentMethod string, optional Method of payment used by the customer.
requestedShippingService string, optional Identifies the shipping service selected by the customer when placing this order. This value is given to ShipStation by the marketplace/cart and helps identify what shipping service the customer selected upon checkout.
carrierCode string, optional The code for the carrier that is to be used(or was used) when this order is shipped(was shipped).
serviceCode string, optional The code for the shipping service that is to be used(or was used) when this order is shipped(was shipped).
packageCode string, optional The code for the package type that is to be used(or was used) when this order is shipped(was shipped).
confirmation string, optional 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. direct_signature is available for FedEx only.
shipDate string, optional The date the order was shipped.
weight Weight, optional Weight of the order. Use the Weight model.
dimensions Dimensions, optional Dimensions of the order. Use the Dimensions model.
insuranceOptions InsuranceOptions, optional The shipping insurance information associated with this order. Use the InsuranceOptions model.
internationalOptions InternationalOptions, optional Customs information that can be used to generate customs documents for international orders. Use the InternationalOptions model.
customsCountryCode string The default two-letter ISO Origin Country code for the Product.
advancedOptions AdvancedOptions, optional Various advanced options that may be available depending on the shipping carrier that is used to ship the order. Use the AdvancedOptions model.
tagIds number[] Array of tagIds. Each tagId identifies a tag that has been associated with this order.

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
}