Create/Update Order

If the orderKey is specified, the method becomes idempotent and the existing order with that key will be updated. 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. cancelled and shipped are locked from modification through the API. The body of this request should specify an Order object:

Name Data Type Description
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.
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.
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": 98765,
    "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": [
    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
}