Bulk API - Resource Dependencies - Adding Resources in the Correct Order

Records of many resources have dependencies on other resources — fields that refer to the value of an id field from a record of another resource — similar to foreign keys in relational database systems.

Tulip enforces these dependencies in Bulk API. Therefore, independent resources must be created before their IDs can be used as foreign keys.

The following diagram provides the high level sequence in which the entities related to each other. The higher level entities must be created first and the IDs will be expected be sent in the subsequent ‘lower’ level entities.

Create OptionTypes and OptionValues Before Creating Products#

OptionTypes and Values are very important to ensure that the Product and Variant record creations do not fail. Option Types are essential variant (item) level classifiers like size, color etc. Each of these option ‘types’ must be created BEFORE sending in a product records that includes child variants.

You must create the OptionTypes and add their corresponding OptionValues before sending variants (Item) level records to Tulip. So before sending a clothing product, create the OptionTypes for colour and size and add the possible values by calling OptionValues target.

These would be two separate calls:

• First, call OptionTypes (such as to create a Colour option type)
  
• Next, call OptionValues (such as to create a list of all colours that can be associated within the product assortment, such as “Red” in EN, “Rouge” in FR)
  
• Now you can call the Variant creation request in a subsequent call.

See the above diagram for ensuring the right sequence is followed before creating the data objects.

Product to Category Relationship#

Product record might have a Categories field containing an array of category IDs. Each of the IDs in this Category array corresponds to the value of the id field for the Category record to which the Product belongs.

Therefore, to create a Product record that belongs to two categories:

1. Create those two Category records to get the values of their record IDs
2. Create the product record specifying those IDs as values of those products' categories fields.

The following is a sample response from the server to a POST call requesting to create two categories, with createdId values of 7 and 8 for two categories:

{
    "newRecords": [
        {
            "jobId": 1,
            "createdId": 7,
            "externalId": "category_654"
        },
        {
            "jobId": 2,
            "createdId": 8,
            "externalId": "cat_1280"
        }
    ],
    "errors": null
}

Note the createdId values in the server response (Category External IDs 7 and 8), then use them in a POST request to the products endpoint, as shown in the following payload fragment:

{
   "categories": [
        7,
        8
    ],
    "dateCreated": "2015-08-11T17:52:31Z",
    "dateModified": "2015-08-12T21:39:10Z",
    "externalId": "SKU5",
    "height": 2.3,
    "images": [
        "products/clue-24_1288972936.jpg"
    ],
    "length": 32.4,
    "limited": false,
    "localizedData": [
        {
            "description": "This is a test",
            "languageId": 1,
            "name": "Another Test Product",
            "subtitle": "Subtitle to be announced",
            "url": "www.xkcd.com"
        }
    ],
    "masterCategory": 1,
    "topCategory": 1,
    "upc": "700304003232",
    "variants": [
        {
        }
    ],
    "videos": [],
    "weight": 8828.3,
    "width": 12.7
} 

Note: Some resources now support partial records which can be used to simplify the sequencing of requests to the Tulip Bulk API.