Partial Records

Partial records are an advanced feature introduced to the Bulk API in Q1 2021 to reduce the complexity of managing dependencies. This feature is only available for integrations using the v2 version of the API.

One of the limitations while working with the Bulk API is that resources need to be created in order. For example, categories must be created before products because products reference a list of categories.

With this new feature, integrations can tell the Bulk API to create a “partial” record if a dependency doesn’t already exist. Partially-created records will be hidden from the app, the actual data should be sent as soon as possible so that the records will show in the app.

Example: Creating a partial category

A new “tee-shirts” category is being added to the app, along with new products. In this example, the product is sent with the following fields before the category has been created:

{
  "externalId": "1e106a66-6cfe-42c6-8dc2-6799bfac0fc4",
  "upc": "012345678905",
  "categories": ["tee-shirts"],
  // ...
}

If a category with external id "tee-shirts" doesn’t exist and partial record creation is not enabled, this record will be rejected:

{
  "updatedRecords": [],
  "createdPartialRecords": null,
  "errors": [
    {
      "jobId": 1,
      "message": "Could not create line number 1: Resource 'category' external ID does not exist",
      "record": "{\"externalId\":\"1e106a66-6cfe-42c6-8dc2-6799bfac0fc4\", \"categories\": [\"tee-shirts\"]}"
    }
  ]
}

However, if partial record creation has been enabled, the record will be accepted:

{
  "updatedRecords": [
    {
      "jobId": 1,
      "updatedId": 54,
      "externalId": "1e106a66-6cfe-42c6-8dc2-6799bfac0fc4"
    }
  ],
  "createdPartialRecords": [
    {
      "jobId": 1,
      "type": "Category",
      "createdId": 32,
      "externalId": "tee-shirts"
    }
  ],
  "errors": null
}

The Bulk API response will contain an additional field createdPartialRecords with a list of all partial records that were created for this request.

Note: If you are using this feature, you should keep track of what partial records have been created so that you can ensure the full data for these resources is sent later.

How to enable partial record creation

Partial record creation can be enabled by adding new query parameter createPartial=true to the existing API endpoint. For example, to enable partially creating categories while updating products, use the following URL:

PUT https://<base-url>/dal/dataAccess/v2/catalog/products?createPartial=true

Resources Supporting Partial Record Creation

This feature is only available for select resources related to maintaining a client’s catalog. The following resources can be created as partial records:

  • Employees
  • Categories
  • Products
  • Variants
  • Orders
  • Inventory
  • Prices

These resources were chosen because they are highly inter-connected and are updated frequently.

Endpoints Supporting Partial Record Creation

Those partial records can be created from the following contexts:

  • When a category is imported that references a parent category that does not exist, that parent category can be created as a partial record.
  • When a product is imported that references a Parent Category that does not exist, that parent category can be created as a partial record.
  • When a variant is imported that references a product that does not exist, that product can be created as a partial record.
  • When inventory is imported that references a product or variant that does not exist, those products and variants can be created as partial records. Stores still need to be imported ahead of time.
  • When prices are imported that reference a product or variant that does not exist, those products and variants can be created as partial records. Stores still need to be imported ahead of time.

To check if an individual endpoint supports partial record creation, check if the createPartial query parameter is available in the API Reference

← Multi-Catalog Hierarchy
Request Format →