Orders

As the name suggests, orders are a core part of SourceOrders — the very reason SourceOrders exists is so you can programmatically manage your orders. On this page, we'll dive into the different order endpoints you can use to manage orders programmatically. We'll look at how to query, create, update, and delete orders.

Order Model

The order model contains all the information about your orders, such as the items in your order, the status of your order, and shipping details. It also contains a reference to your merchant ID on SourceOrders and a self referenced order ID.

Properties

Name
createdDate
Type
string: timestamp
Description
Timestamp of when the order was created.
Name
items
Type
object[]
Description
An array of Objects for all items associated with the order.
Name
lastUpdatedDate
Type
string: timestamp
Description
Timestamp of when the order was last updated by either the merchant or platform.
Name
merchantId
Type
string
Description
The merchant associated with the order.
Name
orderId
Type
string
Description
Unique identifier for the order. Order IDs will always start with soo.
Name
promisedArrivalDate
Type
string: timestamp
Description
Timestamp of when the order is expected to arrive to the shippingAddress.
Name
shippingAddress
Type
object
Description
The shipping address object for the order.
Name
status
Type
string
Description
The status of the order.

GET/v1/orders/:orderId

Retrieve order status

This endpoint allows you to retrieve the status of an order by providing the order id. Refer to the properties list at the top of this page to see which properties are included with order objects.

Request

GET

/v1/orders/soo_3299399716

Production

curl https://api.sourceorders.com/v1/orders/soo_3299399716 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {API KEY}" \

Response

{
  "createdDate": "2023-08-01T14:37:54.869Z",
  "items": [
    {
        "attributes": [
            {
                "name": "link",
                "value": "https://example.com"
            },
            {
                "name": "First Name",
                "value": "Michael"
            },
            {
                "name": "Last Name",
                "value": "Scott"
            },
            {
                "name": "Business Name",
                "value": "Dunder Mifflin"
            }
        ],
        "itemId": "soi_5380620648",
        "skuCode": "sop_0123456789",
        "quantity": 1
    }
  ],
  "lastUpdatedDate": "2023-08-02T10:22:17.971Z",
  "merchantId": "som_0123456789",
  "orderId": "soo_3299399716",
  "promisedArrivalDate": "2023-11-07Z",
  "status": "IN PRODUCTION",
  "shippingAddress": {
    "city": "Hastings",
    "company": "Dunder Mifflin",
    "country": "US",
    "email": "michael.scott@test.com",
    "firstName": "Michael",
    "lastName": "Scott",
    "phone": "866-207-0447",
    "phoneExt": "",
    "postalCode": "55033",
    "stateOrProvince": "MN",
    "street1": "741 Spiral Blvd",
    "street2": ""
  }
}

POST/v1/orders

Create an order

This endpoint allows you to create a new order. To add an order, you must provide the an array of item objects with all required fields and a shippingAddress object.

Required attributes

Name
items
Type
object[]
Description
An array of objects for all items associated with the order. Must include skuCode, quantity, and an array of any required attributes for the associated skuCode.
Name
shippingAddress
Type
object
Description
The shipping address object for the order. For required fields, see the formatting guide.

Request

POST

/v1/orders

Production

curl https://api.sourceorders.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {API KEY}" \
  --data-raw "{
      "items": [
          {
              "attributes": [
                  {
                      "name": "link",
                      "value": "https://www.example.com"
                  }
              ],
              "quantity": 1,
              "skuCode": "sop_0123456789"
          }
      ],
      "shippingAddress": {
          "city": "Hastings",
          "company": "Dunder Mifflin",
          "country": "US",
          "email": "michael.scott@test.com",
          "firstName": "Michael",
          "lastName": "Scott",
          "phone": "866-207-0447",
          "phoneExt": "",
          "postalCode": "55033",
          "stateOrProvince": "MN",
          "street1": "741 Spiral Blvd",
          "street2": ""
      }
  }"

Response

{
  "createdDate": "2023-08-01T14:37:54.869Z",
  "items": [
    "attributes": [
      {
        "name": "link",
        "value": "https://www.example.com"
      }
    ],
    "itemId": "soi_0123456789",
    "quantity": 1,
    "skuCode": "sop_0123456789"
  ],
  "lastUpdatedDate": "2023-10-15T14:37:54.869Z",
  "merchantId": "som_0123456789",
  "orderId": "soo_3299399716",
  "promisedArrivalDate": "2023-11-07Z",
  "shippingAddress": {
    "city": "Hastings",
    "company": "Dunder Mifflin",
    "country": "US",
    "email": "michael.scott@test.com",
    "firstName": "Michael",
    "lastName": "Scott",
    "phone": "866-207-0447",
    "phoneExt": "",
    "postalCode": "55033",
    "stateOrProvince": "MN",
    "street1": "741 Spiral Blvd",
    "street2": ""
  },
  "status": "RECEIVED"
}

PUT/v1/orders/:orderId

Update shipping address

This endpoint allows you to updating the order shipping address by providing the order id and an update body. Updates are only allowed on orders with status RECEIVED. Below we will show which properties are required in the request body.

Required attributes

Name
shippingAddress
Type
object
Description
The shipping address object for the order. For required fields, see the formatting guide.

Request

PUT

/v1/orders/soo_3299399716

Production

curl https://api.sourceorders.com/v1/orders/soo_3299399716 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {API KEY}"
  --data-raw "{
    "shippingAddress": {
      "company": "Michael Scott Paper Company",
      "email": "michael.scott@test.com",
      "phone": "800-555-1234"
    },
  }"

Response

{
  "createdDate": "2023-08-01T14:37:54.869Z",
  "items": [
    {
      . . .
    }
  ],
  "lastUpdatedDate": "2023-10-15T14:37:54.869Z",
  "merchantId": "som_0123456789",
  "orderId": "soo_3299399716",
  "promisedArrivalDate": "2023-11-07Z",
  "shippingAddress": {
    "city": "Hastings",
    "company": "Michael Scott Paper Company"
    "country": "US",
    "email": "michael.scott@test.com",
    "firstName": "Michael",
    "lastName": "Scott",
    "phone": "800-555-1234",
    "phoneExt": "",
    "postalCode": "55033",
    "stateOrProvince": "MN",
    "street1": "741 Spiral Blvd",
    "street2": "",
  },
  "status": "RECEIVED"
}