Skip to main content
The upsert operation allows you to create a resource (if it does not exist) or update it (if it does) in a single API request.

​
How it works

  1. If the resource is not found by the upsert criteria, a new resource is created and 201 Created is returned.
  2. If the resource is found, it is updated and 200 OK is returned.
  3. If multiple resources are found, the operation fails and 409 Conflict is returned.
The upsert criteria is specified in the meta section of the request body using the upsert option:
  • true or ["id"] — match by resource identifier.
  • ["field1", "field2"] — match by specific field(s).

​
Supported methods

MethodCan match by
POSTResource identifier or other field(s)
PATCHResource identifier only
The API Sandbox indicates whether a resource supports the upsert operation in the documentation for POST and PATCH requests.

​
Examples

​
POST: match by resource identifier

Request 
POST /api/weightunits HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Request body 
{
  "data": {
    "type": "weightunits",
    "id": "kg",
    "meta": {
      "upsert": true
    },
    "attributes": {
      "conversionRates": {
        "lbs": 2.2
      }
    }
  }
}

​
PATCH: match by resource identifier

Request 
PATCH /api/weightunits/kg HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Request body 
{
  "data": {
    "type": "weightunits",
    "id": "kg",
    "meta": {
      "upsert": true
    },
    "attributes": {
      "conversionRates": {
        "lbs": 2.2
      }
    }
  }
}

​
POST: match by field

Request 
POST /api/taxjurisdictions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Request body 
{
  "data": {
    "type": "taxjurisdictions",
    "meta": {
      "upsert": ["code"]
    },
    "attributes": {
      "code": "SOME_TAX_JURISDICTION",
      "description": "Some tax jurisdiction description",
      "regionText": null,
      "zipCodes": [
        {"from": "90011", "to": null},
        {"from": "90201", "to": "90280"}
      ]
    },
    "relationships": {
      "country": {
        "data": {
          "type": "countries",
          "id": "US"
        }
      },
      "region": {
        "data": {
          "type": "regions",
          "id": "US-CA"
        }
      }
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us