Overview

Order and shipment models can get quite complex and while we do supply a full rest + graphql endpoints for every model, we also provide a simple upsert functionality.

Upsert is short for update + insert. This means that if you send us a model and we can identify a unique instance of it we will update it, otherwise we will create a new one.

Note: Upsert trades control for convenience. It's really intended for low-code/no-code integrations. It works on best effort basis and will attempt to do the right thing where possible. If you need more control, use the aforementioned rest or graphql endpoints. But it is a great way to get started quickly.

General Upsert Structure

The upsert structure is generally the same for all models. It is a simple JSON object with two fields:

• patch: an optional boolean indicating whether or not to patch the model (defaults to true) see more
• [entity_name]: partial model you want to upsert, this differs per model

The url for the upsert endpoint will be the same as the rest endpoint but with /rpc/upsert_[entity_name] appended to it. You can find all the upsert endpoints in the API Reference.

We'll go over each of these in detail later but for now let's look at an example. Here is an example request against the inventory item upsert endpoint:

POST https://api.channelape.io/rest/v1/rpc/upsert_inventory_item  HTTP/1.1
Content-Type: application/json
apikey: ANON_KEY
Authorization: Bearer YOUR_KEY

{  
  "inventory_item": {
    "business_id": "[your_business_id]",
    "sku": "sku_123",
    "title": "New Title",
  }
}

Here is what the result will be:

{
  "id": "[unique_id]",
  "sku": "sku_123",
  "title": "New Title",
  "business_id": "[your_business_id]",
  "legacy_id": null
}

You may call this endpoint as many times as you like and it will always return the same result. If you change the title to "New Title 2" and call it again, it will update the title and return the same result.

This is because the sku field is unique for inventory items. If you change the sku field to something else, it will create a new inventory item. Why does it matter if sku is unique? Well to explain that, we need to go over how upsert works in the next section.

note

Upserts are only available on REST API V2 and GraphQL.