Orders

Endpoint: POST https://www.shipsidekick.com/api/v1/orders

Minimum Viable Order

We don't need a lot of details to create an order in SSK, only a shipToAddress and lineItems.

{
  "shipToAddress": {
    "name": "John Wick",
    "company": "The Continental",
    "street1": "345 California St.",
    "street2": "",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94104",
    "country": "US",
    "phone": "2504806765",
    "email": "johnwick@example.com"
  },
  "lineItems": [
    {
      "productVariantTitle": "Classic V-Neck Tee",
      "quantity": 1
    }
  ]
}

In this example we'll assign a name to the order with a prefix 'MN' (our default, stands for manual) using the next available integer in that namespace, so if you previously had an order "MN800" the next order will be "MN801".

We'll also generate a default price and compareAtPrice based on the sum of those values on the attached lineItems but we recommend providing them if you have them (especially for international orders!)

By default the new order will get a financialStatus of paid and a fulfillmentStatus of open. Once the order has been fulfilled it will contain shipment details like trackingCode in the shipments array!

Line Items

When creating or updating orders, you can specify line items in multiple ways. The system will automatically find and match the correct product variant based on the identifier you provide.

Line Item Object

Each line item requires at least one identifier field and a quantity. The available identifier fields are:

Field	Type	Description
productVariantId	string	Direct ID of the product variant (most efficient method)
productVariantSku	string	Stock Keeping Unit of the product variant
productVariantBarcode	string	Barcode associated with the product variant
productVariantUpc	string	Universal Product Code
productVariantEan	string	European Article Number
productVariantIsbn	string	International Standard Book Number
productVariantAsin	string	Amazon Standard Identification Number
productVariantTitle	string	Exact title of the product variant

Example Line Item Creation

The following examples show different ways to add the same product to an order:

Using Product Variant ID:

{
  "lineItems": [
    {
      "productVariantId": "var_123abc",
      "quantity": 2,
      "price": 29.99
    }
  ]
}

Using SKU:

{
  "lineItems": [
    {
      "productVariantSku": "WIDGET-RED-LG",
      "quantity": 2,
      "price": 29.99
    }
  ]
}

Using UPC:

{
  "lineItems": [
    {
      "productVariantUpc": "123456789012",
      "quantity": 2,
      "price": 29.99
    }
  ]
}

Using Title:

{
  "lineItems": [
    {
      "productVariantTitle": "Widget - Red, Large",
      "quantity": 2,
      "price": 29.99
    }
  ]
}

Error Handling

If no product variant is found with the provided identifiers, the API will return a 400 error with details about which identifier failed to match:

{
  "error": {
    "message": "Product variant not found with SKU: WIDGET-RED-XL",
    "code": "product_variant_not_found"
  }
}