Items

Items are an essential part of SourceOrders — they allow you to control product quantities, variations/versions, encoding, art links, and more. You are able to freely define all attributes unique to your product. We'll look at how to query, create, update, and delete items.

The item model

The item model contains all the information about the items in your order.

Properties

Name
attributes
Type
object[]
Description
Array of objects for a product. Each object contains keys "name" and "value". You may add any number of attributes, however your order must include the product's required attributes if any exist. Eg. quantity, encoding, art links, etc.
Name
itemId
Type
string
Description
Unique identifier, within the order, for the item. The itemId will always begin with soi.
Name
quantity
Type
number
Description
Amount of that product to be shipped.
Name
skuCode
Type
string
Description
Unique identifier for the product. The skuCode will always begin with sop.

GET/v1/items/:orderId

List order items

This endpoint allows you to list of all your items from an order.

Request

GET

/v1/items/soo_3299399716

Production

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

Response

[
    {
        "attributes": [
            {
                "name": "link",
                "value": "https://bitsignal.io/nick"
            },
            {
                "name": "First Name",
                "value": "Nick"
            },
            {
                "name": "Last Name",
                "value": "Stull"
            },
            {
                "name": "Business Name",
                "value": "BitSignal"
            }
        ],
        "itemId": "soi_5380620648",
        "quantity": 50,
        "skuCode": "sop_0123456789"
    },
    . . .
]

POST/v1/items/:orderId

Add items

This endpoint allows you to add new items to an existing order. The data sent in the request is an array of objects to be added to an existing order.

Required attributes

Example object in array

Name
attributes
Type
object[]
Description
Array of objects. For formatting, see the formatting guide.
Name
skuCode
Type
string
Description
SKU Code for the given item being added.
Name
quantity
Type
number
Description
Amount of a given product with the specifications listed in attributes.

Request

POST

/v1/items/soo_3299399716

Production

curl https://api.sourceorders.com/v1/items/soo_3299399716 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {API KEY}" \
  --data-raw "{[
    {
      "attributes": [
        {
          "name": "link",
          "value": "https://www.example.com"
        },
        {
          . . .
        }
      ],
      "quantity": 1,
      "skuCode": "sop_0123456789"
    }
  ]}"

Response

{
  "createdDate": "2023-08-01T14:37:54.869Z",
  "items": [
    {
      "attributes": [
        {
          "name": "link",
          "value": "https://www.example.com"
        },
        {
          . . .
        }
      ],
      "itemId": "soi_1234567890",
      "quantity": 1,
      "skuCode": "sop_0123456789"
    },
    {
      . . .
    }
  ],
  "lastUpdatedDate": "2023-10-15T14:37:54.869Z",
  "merchantId": "som_0123456789",
  "orderId": "soo_3299399716",
  "promisedArrivalDate": "2023-11-07Z",
  "shippingAddress": {
    . . .
  },
  "status": "RECEIVED"
}

PUT/v1/items/:orderId

Update item(s)

This endpoint allows you to update items by providing the itemId. The itemId for each item can be retrieved by using the GET request. Refer to the list at the top of this page to see which properties are included with item objects.

Example object in array

Required attributes

Name
itemId
Type
string
Description
The itemId generated by SourceOrders. This will begin with soi_.

Optional attributes

Name
attributes
Type
object[]
Description
Array of objects. For formatting, see the formatting guide.
Name
quantity
Type
number
Description
The updated number of units of a product.
Name
skuCode
Type
string
Description
The SKU code for a different product this item should refer to.
NOTE: If skuCode is updated, the required attributes for the new product, if any, must also be sent.

Request

PUT

/v1/items/soo_3299399716

Production

curl https://api.sourceorders.com/v1/items/soo_3299399716 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {API KEY}" \
  --data-raw "{[
    {
        "attributes": [
          {
            "name": "link",
            "value": "https://example.org"
          },
          { . . . }
        ],
        "itemId": "soi_0123456789",
        "quantity": 25,
        "skuCode": "sop_0123456789"
    }
  ]}"

Response

{
  "createdDate": "2023-08-01T14:37:54.869Z",
  "items": [
    {
      "attributes": [
          {
            "name": "link",
            "value": "https://example.org"
          },
          { . . . }
        ],
        "itemId": "soi_0123456789",
        "quantity": 25,
        "skuCode": "sop_0123456789"
    },
    {
      . . .
    }
  ],
  "lastUpdatedDate": "2023-10-15T14:37:54.869Z",
  "merchantId": "som_0123456789",
  "orderId": "soo_3299399716",
  "promisedArrivalDate": "2023-11-07Z",
  "shippingAddress": {
    . . .
  },
  "status": "RECEIVED"
}