Specific Data Types

Date Format

Many records have date-related fields: dateCreated and dateModified.

The values for these fields are JSON strings with Z-normalized (UTC) RFC 3339 timestamp formatting. For example, “Saturday, 28 January 1972 at 10:00:20 AM UTC” would be represented as:

1972-01-28T10:00:20.000Z

Handling Resources that have Date Values

When handling resources withdateCreatedanddateModifiedfields, the Bulk API service applies the following special rules depending on whether it’s a POST (create) or a PUT (update) request.

Date FieldHandled in POST RequestsHandled in PUT Requests
dateCreatedIf the request contains a value, that date/time is used.
If the request does not contain a value, the current date/time is automatically set.		Ignored and cannot be updated
dateModifiedIgnored and set to nullIf the request contains a value, that date/time is used.
If the request does not contain a value, the current date/time is automatically set.

Phone Numbers

Values of phone number fields must conform to the E.164 standard:

 [+] [country code] [area code ] [local phone number]

States & Provinces

Values of fields for provinces and state strings must conform to ISO-3166-2.

Countries

Values of fields for country strings must conform to ISO-3166-3.

Store records contain fields called "countryId". A list of all countries can be retrieved from the "idmappings" field via /dataAccess/v2/idMappings/countries Consider the following JSON structure:

{
    "id": 15,
    "externalId": "store_42",
    "countryId": 123,
    ...
}

In the above example,

  • 15 is the record-level internal ID
  • store_42 is the record’s external ID as (string)
  • 123 is the country’s internal ID (integer)

Note that if the record level “id”: 15 was skipped entirely or had a value 0 in it, the update (PUT) request would look for the existing record by its external ID value — "externalId": "store_42".

An alternative to using internal IDs for mapping country and a zone records is to use external ID strings directly as the values for these fields. For example, your payload might be based on the following initial JSON structure:

{
    "id": 15,
    "externalId": "store_42",
    "countryId": "USA",
    "zoneId": "US-NY",
    ...
}

In this case, before creating or updating country and zone records, the system will automatically resolve:

  • the external ID of the country record from “USA” to the internal ID value of the country record.
  • the external ID of the zone record from US-NY to the internal ID value of the zone record.
← Request Format
Support →