Product Information Management API (1.3.0)

Download OpenAPI specification:Download

The Product Information Management API is a mechanism to transact product data within the 3D Cloud ecosystem.

Documentation

API Documentation HTML

View the API Documentation in HTML format

Responses

Product Information Management

Open Batch

Opens a batch if it was previously closed.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
batchName
required
string

The batch name

clientId
required
string

The client id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientId": "string",
  • "topLoaded": true,
  • "keyLoaded": true,
  • "optLoaded": true,
  • "autoPromote": true,
  • "topCatalogRelease": "string",
  • "topSlHeader": "string",
  • "lastUpdated": {
    },
  • "closed": false
}

Close Batch

Closes a batch so it can't be used in the future. (Use in favor of DELETE /batches). If an auto-migrate PIM function is in place upon closing the batch, the data will automatically be migrated.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
batchName
required
string

The batch name

clientId
required
string

The client id

autoPromote
boolean
Default: false

When closing this batch, should the data be automatically available/live for the staging and active environments?

publishTarget
string
Default: "latest"

Sets the publish target tag where the data will be published to. By default, the data is published into the 'latest' target. If 'autoPromote' is true, this data is published into 2 targets automatically (staging, active). This is also useful for sandbox environments where you want data temporarily published for testing purposes.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientId": "string",
  • "topLoaded": true,
  • "keyLoaded": true,
  • "optLoaded": true,
  • "autoPromote": true,
  • "topCatalogRelease": "string",
  • "topSlHeader": "string",
  • "lastUpdated": {
    },
  • "closed": false
}

Get Batches

Gets a list of batches

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

pageSize
integer
Default: 25

The page size of results to return

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientId": "string",
  • "topLoaded": true,
  • "keyLoaded": true,
  • "optLoaded": true,
  • "autoPromote": true,
  • "topCatalogRelease": "string",
  • "topSlHeader": "string",
  • "lastUpdated": {
    },
  • "closed": false
}

Create Batch

Creates a new batch

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
batchName
string

A user defined batch name (optional). If no batch name is supplied, one will be created for you in a date/time format.

clientId
required
string

The client id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientId": "string",
  • "topLoaded": true,
  • "keyLoaded": true,
  • "optLoaded": true,
  • "autoPromote": true,
  • "topCatalogRelease": "string",
  • "topSlHeader": "string",
  • "lastUpdated": {
    },
  • "closed": false
}

Close Batch Deprecated

Closes a batch so it can't be used in the future. (Deprecated as of 1.0.2 - In favor of POST /batches/close)

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
batchName
string

The batch name

clientId
required
string

The client id

autoPromote
boolean
Default: false

When closing this batch, should the data be automatically available/live for the staging and active environments?

publishTarget
string
Default: "latest"

Sets the publish target tag where the data will be published to. By default, the data is published into the 'latest' target. If 'autoPromote' is true, this data is published into 3 targets automatically (latest, staging, active). This is also useful for sandbox environments where you want data temporarily published for testing purposes.

Responses

Response samples

Content type
application/json
true

Get Batch Data

Gathers product data for the given batch, and returns a url from which the data can be downloaded.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
path Parameters
id
required
string

The id for the batch containing the product data to retrieve

Responses

Get Publish Target Data

Gathers product data for the given publish target, and returns a url from which the data can be downloaded.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
path Parameters
id
required
string

The publish target containing the product data to retrieve

Responses

Save or Update Products

Saves or Updates a list of products.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
batchName
required
string

The batch name

clientId
required
string

The client id

autoPromote
boolean
Default: false

Automatically promote this content state to staging and active (available to the live environments). If true, this will also close the batch. If an auto-migrate PIM function is in place upon closing the batch, the data will automatically be migrated.

autoCloseBatch
boolean
Default: true

Automatically closes the batch when the products are saved

publishTarget
string
Default: "latest"

Sets the publish target tag where the data will be published to. By default, the data is published into the 'latest' target. If 'autoPromote' is true, this data is published into 2 targets automatically (staging, active). This is also useful for sandbox environments where you want data temporarily published for testing purposes.

Request Body schema: application/json

Array of Product objects

id
required
string

The primary key. This should be a unique id across the product catalog.

name
string

The product name.

sku
required
string

The product SKU. This is case sensitive.

mfgSku
string

The manufacturer SKU. This is case sensitive.

mfgName
string

The manufacturer name.

description
string

The product description.

dimensions
string

The product dimensions.

defaultPrice
number <float>

The product price.

defaultCurrency
string

The product price currency. This uses the ISO 4217 standard [USD, EUR, etc...].

categories
Array of strings

A list of category names.

categoryTree
Array of strings[ items ]

A list of category paths. Each path is an ordered array of category names from parent to child (e.g. ["Living Room", "Chairs", "Green"]). The order of the names defines the parent/child relationship between the categories, so the order must be preserved.

Array of objects (ProductGroup)

A list of product groups. See the ProductGroup object for more details.

pdpURL
string

The product description page URL.

imageURLs
Array of strings

A list of image URLs relative to this product.

brand
string

The product brand.

finish
string

The product finish.

color
string

The product color.

family
string

The product family.

discount
string

The product discount. This can be a price, percentage or text.

promo
string

The product promotion. This can be a price, percentage or text.

defAtrName1
string

A definition attribute name. This can be used to store arbitrary data.

defAtrVal1
string

A definition attribute value. This can be used to store arbitrary data.

defAtrName2
string

A definition attribute name. This can be used to store arbitrary data.

defAtrVal2
string

A definition attribute value. This can be used to store arbitrary data.

defAtrName3
string

A definition attribute name. This can be used to store arbitrary data.

defAtrVal3
string

A definition attribute value. This can be used to store arbitrary data.

defAtrName4
string

A definition attribute name. This can be used to store arbitrary data.

defAtrVal4
string

A definition attribute value. This can be used to store arbitrary data.

defAtrName5
string

A definition attribute name. This can be used to store arbitrary data.

defAtrVal5
string

A definition attribute value. This can be used to store arbitrary data.

defAtrName6
string

A definition attribute name. This can be used to store arbitrary data.

defAtrVal6
string

A definition attribute value. This can be used to store arbitrary data.

skuType
string

Type of the product - Is it a SKU, Installation SKU, Non-Selling, etc...

Array of objects (Region)

A list of regions. See the Region object for more details.

Responses

Request samples

Content type
application/json
{
  • "id": "928532",
  • "name": "Analog Round Wall Industrial Clock",
  • "sku": "928532",
  • "mfgSku": "928532",
  • "mfgName": "Industrial Clock",
  • "description": "Decorative wall clock. Industrial-style decorative wall clock. Distressed metal frame finish with deep profile. Dark oil rubbed bronze finish. Ready to hang.",
  • "dimensions": "30x30x10.75",
  • "defaultPrice": 72.98,
  • "defaultCurrency": "USD",
  • "categories": [
    ],
  • "categoryTree": [
    ],
  • "productGroups": [
    ],
  • "brand": "Mr. Clean",
  • "finish": "Bronze",
  • "color": "Brown",
  • "family": "Brown",
  • "discount": "2%",
  • "promo": "Free Shipping",
  • "defAtrName1": "Display Type",
  • "defAtrVal1": "Analog",
  • "defAtrName2": "Battery Size",
  • "defAtrVal2": "AA",
  • "defAtrName3": "",
  • "defAtrVal3": "",
  • "defAtrName4": "",
  • "defAtrVal4": "",
  • "defAtrName5": "",
  • "defAtrVal5": "",
  • "defAtrName6": "",
  • "defAtrVal6": "",
  • "skuType": "Installation SKU",
  • "regions": [ ]
}

Get State History

Get a list of State History

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

createdTimeCursor
string

The created time cursor which is used to offset the results

pageSize
integer
Default: 25

The number of results returned

setBefore
boolean
Default: false

True if the results returned should come after the createdTimeCursor. False to come before.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "states": {
    },
  • "stateHistoryType": "AUTO_PROMOTE",
  • "updateTime": {
    }
}

Get States

Get the current environment states (latest, staging, active)

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

Responses

Response samples

Content type
application/json
"string"

Update A State

Set an environment state (latest, staging, active)

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

state
required
string

The state (latest, staging or active)

batchName
required
string

The batch name

publishTarget
string
Default: "latest"

Sets the publish target tag where the data will be published to.

Responses

Response samples

Content type
application/json
"string"

State Auto Promote

Automatically promotes the provided batch name to staging and active

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

batchName
required
string

The batch name being promoted

publishTarget
string
Default: "latest"

Sets the publish target tag where the data will be published to. This data is published into 2 targets automatically (staging, active).

Responses

Response samples

Content type
application/json
"string"

Publish Target Sync

Syncs a source publish target to a destination publish target. This can be used for promoting content to different states (latest to staging). It can also be used to send data to a sandbox destination for testing purposes.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

source
required
string

The source publish target you want to copy data FROM

target
required
string

The destination publish target you want to copy data TO

replace
boolean

If you want the source data to replace the existing document data or merge (default)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "message": "string"
}

Get Publish Target Sync Status

Gets the status of publish target sync

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
clientId
required
string

The client id

sourcePublishTarget
required
string

The source publish target

statusId
string

The status id

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "lastUpdated": {
    },
  • "source": "string",
  • "destination": "string"
}

Standard Interchange Format (SIF)

Upload SIF Top File

Uploads a new SIF Top file (if less than or equal to 32MB - for anything larger than 32MB use 'Upload SIF Request')

Authorizations:
APIKeyHeaderAPIKeyQueryParam
Request Body schema: multipart/form-data
file
required
string

The top file

batchName
required
string

The batch name

clientId
required
string

The client id

group
required
string

The group - this is used in cases where you have multiple files separated by family, category or other strategies

Responses

Upload SIF Opt File

Uploads a new SIF Opt file (if less than or equal to 32MB - for anything larger than 32MB use 'Upload SIF Request')

Authorizations:
APIKeyHeaderAPIKeyQueryParam
Request Body schema: multipart/form-data
file
required
string

The opt file

batchName
required
string

The batch name

clientId
required
string

The client id

group
required
string

The group - this is used in cases where you have multiple files separated by family, category or other strategies

Responses

Upload SIF Key File

Uploads a new SIF Key file (if less than or equal to 32MB - for anything larger than 32MB use 'Upload SIF Request')

Authorizations:
APIKeyHeaderAPIKeyQueryParam
Request Body schema: multipart/form-data
file
required
string

The key file

batchName
required
string

The batch name

clientId
required
string

The client id

group
required
string

The group - this is used in cases where you have multiple files separated by family, category or other strategies

Responses

Upload SIF Request

Request to upload SIF files larger than 32MB. This request returns a Signed URL which allows you to upload directly to the specified file. This requires a second PUT request using the response URL (from this request) and the file itself as the body binary.

The follow-up PUT request must contain 3 header values:

  • x-goog-meta-sifgroup The sifgroup must be the same group you supplied for the upload/request value
  • x-goog-meta-siftype The siftype must be the same type you supplied for the upload/request value
  • Content-Type application/octet-stream

Facts:

  • Must be a PUT request
  • Content-Type must be application/octet-stream
  • The returned Signed URL is only good for 300 seconds. The file PUT request must be initiated within this timeframe, otherwise you will need to run another Upload Request.

Examples: curl -X PUT -H 'Content-Type: application/octet-stream' --header 'x-goog-meta-sifgroup: myGroup' --header 'x-goog-meta-siftype: top' --upload-file my-file URL

For Postman, use the Body request 'binary' option and select the file you want to upload.

Authorizations:
APIKeyHeaderAPIKeyQueryParam
query Parameters
filename
required
string

The filename requesting to be uploaded

batchName
required
string

The batch name

clientId
required
string

The client id

group
required
string

The group - this is used in cases where you have multiple files separated by family, category or other strategies

type
required
string

The SIF type being requested to upload - can be one of (top, key, opt)

Responses