Writing to a resource

To write to a resource we can use the POST and PUT HTTP methods. Which one we use will depend on the type of write we are wanting, and how strict we are wanting it to be.

Creating a new record

To create / save a record, we submit form encoded variables or XML to the resource url using the POST method. If POSTing XML data, ensure you specify the 'text/xml' content type.

So to create a new product, we would POST valid XML to /API/V3/Products.

If you POST to a specific resource the API will first check if a record matching the received XML payload already exists in the system (by comparing primary keys):

If the record does not already exist, it will be created.
If the record already exists, the existing record will instead be updated

So a POST can actually be used to create or update a resource.

It is important to note that your XML must still be wrapped in a <ResultSet> node. Failure to do so will result in a 400 Bad Request error as the system will be unable to successfully find the first XML node.

An example of a POST to create a new product might look like this:

POST /API/V3/Products

<?xml version="1.0"?>
<ResultSet>
  <Product>
    <sku>foo-sku</sku>
    <title>Foo product title</title>
    <price>21.20</price>
    <!-- etc -->
  </Product>
</ResultSet>

Any passed inline attributes in the XML will be ignored (e.g. <Product href="..." attribute2="abc">).

Only the fields you wish to set need to be defined. All others will be ignored (e.g. when updating)

Saving multiple records

You can save multiple records at once by POSTing them to the same resource endpoint - simply including additional nodes inside the ResultSet. If you need to write many records, you should definitely batch them up & send them in a few requests, rather than writing them one at a time and causing unnecessary load on our servers.

Saving related records

You can also save related records in the same API request - simply by submitting a POST back to the same resource specification endpoint that you would retrieve the records from had you submitted a GET request.

Tip: to verify you have the correct resource specification, submit a GET request first & compare the XML response to your payload

From there, provided your payload is correct, the Data API will then create records for all related records in the single POST request. This approach can also be combined with saving multiple records above.

For example you could create multiple new products, with associated inventory records by POSTing the following XML to /API/V3/Products+Inventory:

<?xml version="1.0"?>
<ResultSet>
  <Product>
    <sku>foo-sku</sku>
    <title>Foo product title</title>
    <price>21.20</price>
    <Inventory>
      <quantity>55</quantity>
      <sku>foo-sku</sku>
      <stock_message>New Stock Now!</stock_message>
    </Inventory>
    <!-- etc -->
  </Product>
  <Product>
    <sku>bar-sku</sku>
    <title>Bar product title</title>
    <price>15.00</price>
    <image>new_image2.jpg</image>
    <Inventory>
      <quantity>12</quantity>
      <sku>bar-sku</sku>
    </Inventory>
    <!-- etc -->
  </Product>
</ResultSet>

Updating a record

When updating a record, we have a choice of either using POST or PUT. The two are very similar, except a PUT will enforce an update - throwing an error if the specified key cannot be found in the resource.

To update a resource we PUT form encoded variables or XML to the resource instance url that we are wanting to update. So to update order ORD00025 (and return an error if it doesn't exist) we PUT to:

/API/V3/Order/ORD00025

Updating multiple records with PUT

If we are performing a multiple update, we can PUT XML (with a text/xml content type) to the resource url (i.e. as opposed to a specific record url). It is important to note that if a specific record url is passed, the record key is ignored as this should be specified in the XML that you have PUT for the update.

This allows us to GET one or more records using a retrieve or search method, update the data as required (e.g. using xpaths, xslt, or parsing & regenerating the xml), and then PUT it straight back. You don't need to worry about any extra attributes in the XML received from the API (e.g. href, id) as the system ignores these.

Response

The response received by a successful POST or PUT will contain a rsp node with an attribute of stat="ok":

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok" version="3.0">
  <success>1</success>
</rsp>

Error response

If an error occurred, the stat attribute will be set to fail and the XML response will contain more information:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="fail" version="3.0">
    <error>
        <key></key>
        <code>404</code>
        <interface>Product</interface>
        <msg>Record with specified key does not exist</msg>
    </error>
</rsp>

See error responses for more information.