Bulk Data Operations with Internal & External IDs

Operations using the Bulk API service involve submitting requests to retrieve or modify records identified by their IDs.

In order to GET (retrieve) and PUT (update) records using the Bulk API, you must identify the record either the id or externalId field. The id field is generated by Tulip upon initial record creation in the Tulip Platform backend whereas the externalId must be provided by the client during record creation.

Retrieving (GET) by “externalId”#

To get a record by its externalId , a GET request can be made to the get by ID endpoint with an externalId querystring parameter instead of a URL parameter. For example, to get a Product record, submit the following API call:

GET /dataAccess/v1/catalog/products?externalId={external_id} 

Updating (PUT) by “externalId”#

Updates by externalId are done implicitly when an record in a PUT request does not contain an id field or the id has a value of 0. If a record with the given externalId does not exist, it will be created.

Resolving External IDs to Tulip IDs#

Relationships between records in the Tulip data model are specified through fields ending in Id and ExternalId.

For example, store records are related to zones and countries; when you fetch a store record from the Bulk API, you will see the following fields:

{
    "id": 15,
    "externalId": "store_42",
    "zoneId": 3930,
    "zoneExternalId": "US-NY",
    "countryId": 223,
    "countryExternalId": "USA",
    // ...
}

In the above example,

• 15 is the store’s internal ID
• store_42 is the store’s external ID
• 223 is the country’s internal ID
• USA is the country’s external ID
• 3930 is the zone’s internal ID
• US-NY is the zone’s external ID

The external ID fields (zoneExternalId and countryExternalId in this example) are read-only fields; they are populated only when a record is retrieved through the Bulk API.

When creating or updating a store using a PUT or POST request, you can specify the zoneId and countryId fields using either the internal OR the external id.

For example, sending a store with the following fields:

{
    "countryId": "USA",
    "zoneId": "US-NY",
    // ...
}

is the same as:

{
    "countryId": 223,
    "zoneId": 3930,
    // ...
}

The Tulip Bulk API will determine whether you are referencing the internal or external ID based on whether you send this field as an integer or a string. As a result, sending "countryId":"223" is NOT the same as the above requests.

To determine whether external ids can be used for an individual field, check the API specification and look for the term “externalId resolvable” in the field description.

Important Note: The processing involved in automatically resolving external IDs might have an adverse effect on system performance; therefore, obtaining Tulip internal IDs using the IdMappings endpoint before invoking the actual PUT/POST API calls is highly recommended. Additionally, Tulip recommends that partners/clients explore ways to maintain the Tulip IDs on their side for optimized performance.