Configurations API

Saves a configuration.

Saves the configuration of a product and generates a shortID which can be used to retrieve the configuration, in place of the UUID.

REST Endpoint

POST https://admin.threekit.com/api/configurations?bearertoken=[bearertoken]

Query Parameters

Name	In	Type	Required	Description
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.
body	body	configurationBody	true	Configuration information to be saved.

Body Parameters

{
  "orgId": "7f6a52b7-a10b-4945-836a-5fecc24ee914",
  "productId": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
  "productVersion": "exampleVersionNumber",
  "variant": {
    "ExampleVariantField1": "ExampleValue1"
  },
  "metadata": {
    "SKU": "exampleSKU"
  },
  "files": "string",
  "shortId": "46Juzcyx",
  "customerId": "bba8a2d8-528e-4a20-beea-bc59f7863dcb"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful POST request, response body will include the created configuration details.	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	User is authenticated but lacks authorization to use this service	None
422	Unprocessable Entity	The configuration information provided in the request is missing mandatory fields	None

Examples

Code

CURL

curl --request POST \
  --url https://admin.threekit.com/api/configurations \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data '{"orgId":"7f6a52b7-a10b-4945-836a-5fecc24ee914","productId":"e5d536ec-e89c-46fc-8773-7e54ba70517a","productVersion":"exampleVersionNumber","variant":{"ExampleVariantField1":"ExampleValue1"},"metadata":{"SKU":"exampleSKU"},"files":"string","shortId":"46Juzcyx","customerId":"bba8a2d8-528e-4a20-beea-bc59f7863dcb"}'

Node.JS

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/configurations",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ orgId: '7f6a52b7-a10b-4945-836a-5fecc24ee914',
  productId: 'e5d536ec-e89c-46fc-8773-7e54ba70517a',
  productVersion: 'exampleVersionNumber',
  variant: { ExampleVariantField1: 'ExampleValue1' },
  metadata: { SKU: 'exampleSKU' },
  files: 'string',
  shortId: '46Juzcyx',
  customerId: 'bba8a2d8-528e-4a20-beea-bc59f7863dcb' }));
req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/configurations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"orgId\":\"7f6a52b7-a10b-4945-836a-5fecc24ee914\",\"productId\":\"e5d536ec-e89c-46fc-8773-7e54ba70517a\",\"productVersion\":\"exampleVersionNumber\",\"variant\":{\"ExampleVariantField1\":\"ExampleValue1\"},\"metadata\":{\"SKU\":\"exampleSKU\"},\"files\":\"string\",\"shortId\":\"46Juzcyx\",\"customerId\":\"bba8a2d8-528e-4a20-beea-bc59f7863dcb\"}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

200 Response

{
  "myConfiguration": {
    "summary": "An example of successful creation of configuration",
    "value": [
      {
        "id": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
        "productId": "b227b582-4e16-4a30-870d-a3dc8ecbe5fd",
        "productVersion": "exampleVersionNumber",
        "variant": {
          "ExampleVariantField1": "ExampleValue1"
        },
        "metadata": {},
        "shortId": "46Juzcyx",
        "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22f6405a02b0e0d434e7814b6761444fda01-br",
        "createdAt": "2019-06-06 15:10:25.471+00"
      }
    ]
  }
}

User is not authenticated. They must be authenticated to use this service.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

User is authenticated but lacks authorization to use this service

{
  "error": {
    "code": "forbidden",
    "message": "Forbidden"
  }
}

The configuration information provided in the request is missing mandatory fields

{
  "error": {
    "code": "create_configuration_error",
    "message": "Create configuration error"
  }
}

Retrieves a list of configurations.

Retrieves a list of all configurations associated with an organization. Each configuration will have the following information.

id - Configuration ID
productId - ID of the product
productVersion - Version of the product. NOTE --- This is related to our publishing workflow, which is still in the process of being implemented. As of now, this parameter can be safely ignored.
shortId - Automatically generated shortID. It can be used in place of the id field
variant - Configuration variant information (If present). This refers to the product attributes and their values.
metadata - Metadata information associated with the configuration (If present)
orgId - Organization ID
thumbnail - Hash of the thumbnail of the configuration (If present)
createdAt - Configuration creation timestamp

REST Endpoint

GET https://admin.threekit.com/api/configurations?bearertoken=[bearertoken]&orgId=[orgId]&productId=[productId]&productVersion=[productVersion]&shortId=[shortId]&sku=[sku]&metadata=[metadata]&fullConfiguration=[fullConfiguration]

Query Parameters

Name	In	Type	Required	Description
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.
orgId	query	string	false	Organization ID.
productId	query	string	false	Product ID.
productVersion	query	string	false	Product version.
shortId	query	string	false	Short ID.
sku	query	string	false	SKU of the configuration.
metadata	query	string	false	Arbitrary metadata to be used to fetch list of configurations. Since it is a query string parameter, it needs to be correctly stringified and encoded. Example 'metadata={%22Example%20Key%22:%Value%22}'
fullConfiguration	query	boolean	false	Fetches detailed information about the configuration, specifically item name and item metadata for part references. **NOTE - The current implementation assumes that the format of the variant field is identical to how the player stores configuration. For a custom format, there is a possibility that it may not work

Responses

Status	Meaning	Description	Schema
200	OK	Successful GET request. Response body will include list of configurations.	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	User is authenticated but lacks authorization to use this service	None
404	Not Found	No configurations exist in the database, based on the query parameter(s) provided.	None

Examples

Code

CURL

curl --request GET \
  --url https://admin.threekit.com/api/configurations \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/configurations",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/configurations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

Successful GET request. Response body will include list of configurations.

{
  "configurations": [
    {
      "id": "0dcbbee1-352e-4f3b-b87d-3c007b33b3f1",
      "productId": "77a70069-212a-4c9a-be20-bc054bbd0127",
      "productVersion": "exampleVersionNumber2",
      "orgId": "b386f503-d2d3-425d-8b2b-5e4c39da510d",
      "variant": {
        "Pillows": "Hide"
      },
      "metadata": {
        "SKU": "exampleSKU"
      },
      "shortId": "hwX6aOr7",
      "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22g6405q02b0e0d434e7814b676354fda01",
      "createdAt": "2019-06-06 15:10:25.471+00"
    },
    {
      "id": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
      "productId": "b227b582-4e16-4a30-870d-a3dc8ecbe5fd",
      "productVersion": "exampleVersionNumber",
      "variant": {},
      "metadata": {
        "SKU": "exampleSKU"
      },
      "shortId": "46Juzcyx",
      "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22f6405a02b0e0d434e7814b6761444fda01",
      "createdAt": "2019-06-06 15:10:25.471+00"
    }
  ]
}

User is not authenticated. They must be authenticated to use this service.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

User is authenticated but lacks authorization to use this service

{
  "error": {
    "code": "forbidden",
    "message": "Forbidden"
  }
}

No configurations exist in the database, based on the query parameter(s) provided.

{
  "error": {
    "code": "configurations_not_found",
    "message": "Configurations not found"
  }
}

Retrieves a list of configurations by SKU.

Retrieves a list of all configurations associated with a SKU. Each configuration will have the following information.

id - Configuration ID
productId - ID of the product
productVersion - Version of the product. NOTE --- This is related to our publishing workflow, which is still in the process of being implemented. As of now, this parameter can be safely ignored.
shortId - Automatically generated shortID. It can be used in place of the id field
variant - Configuration variant information (If present). This refers to the product attributes and their values.
metadata - Metadata information associated with the configuration (If present)
orgId - Organization ID
thumbnail - Hash of the thumbnail of the configuration (If present)
createdAt - Configuration creation timestamp
scope - Scope of the SKU, only allows 'GTIN', 'UPC' and 'org'
identifier - Identifier of the SKU

REST Endpoint

GET https://admin.threekit.com/api/configurations/sku?bearertoken=[bearertoken]&sku=[sku]

Query Parameters

Name	In	Type	Required	Description
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.
sku	query	string	true	SKU of the configuration.

Responses

Status	Meaning	Description	Schema
200	OK	Successful GET request. Response body will include list of configurations.	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
404	Not Found	SKU was not passed	None

Examples

Code

CURL

curl --request GET \
  --url 'https://admin.threekit.com/api/configurations/sku?sku=sku%3D'\''xyz-123'\''' \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/configurations/sku?sku=sku%3D'xyz-123'",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/configurations/sku?sku=sku%3D'xyz-123'",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

Successful GET request. Response body will include list of configurations.

{
  "configurations": [
    {
      "id": "0dcbbee1-352e-4f3b-b87d-3c007b33b3f1",
      "productId": "77a70069-212a-4c9a-be20-bc054bbd0127",
      "productVersion": "exampleVersionNumber2",
      "orgId": "b386f503-d2d3-425d-8b2b-5e4c39da510d",
      "variant": {
        "Pillows": "Hide"
      },
      "metadata": {
        "SKU": "exampleSKU"
      },
      "shortId": "hwX6aOr7",
      "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22g6405q02b0e0d434e7814b676354fda01",
      "createdAt": "2019-06-06 15:10:25.471+00"
    },
    {
      "id": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
      "productId": "b227b582-4e16-4a30-870d-a3dc8ecbe5fd",
      "productVersion": "exampleVersionNumber",
      "variant": {},
      "metadata": {
        "SKU": "exampleSKU"
      },
      "shortId": "46Juzcyx",
      "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22f6405a02b0e0d434e7814b6761444fda01",
      "createdAt": "2019-06-06 15:10:25.471+00"
    }
  ]
}

User is not authenticated. They must be authenticated to use this service.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

SKU was not passed

{
  "error": {
    "code": "configuration_not_found",
    "message": "sku param required"
  }
}

Retrieves a configuration from its ID or shortID.

REST Endpoint

GET https://admin.threekit.com/api/configurations/{id}?bearertoken=[bearertoken]

Query Parameters

Name	In	Type	Required	Description
id	path	string	true	ID or shortID of the configuration to be retrieved.
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.

Responses

Status	Meaning	Description	Schema
200	OK	Successful GET request, retrieving a configuration using its ID or short ID.	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
404	Not Found	No configuration was found with the given ID or short ID.	None

Examples

Code

CURL

curl --request GET \
  --url https://admin.threekit.com/api/configurations/string \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/configurations/string",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/configurations/string",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

Successful GET request, retrieving a configuration using its ID or short ID.

[
  {
    "id": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
    "productId": "b227b582-4e16-4a30-870d-a3dc8ecbe5fd",
    "productVersion": "exampleVersionNumber",
    "variant": {},
    "metadata": {},
    "shortId": "46Juzcyx",
    "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22f6405a02b0e0d434e7814b6761444fda01",
    "createdAt": "2019-06-06 15:10:25.471+00"
  }
]

[
  {
    "id": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
    "productId": "b227b582-4e16-4a30-870d-a3dc8ecbe5fd",
    "productVersion": "exampleVersionNumber",
    "variant": "{ \"exampleAttr1\": \"exampleValue1\", \"examplePartRef1\": { \"type\": \"item\", \"assetId\": \"cd2170fb-c18d-4112-86a5-de6cb7fe3d1a\", \"configuration\": { \"nestedAttr1\": \"nestedAttrValue1\", } \"itemName\": \"ExampleItem\", \"itemMetadata\": {} } } }",
    "metadata": {},
    "shortId": "46Juzcyx",
    "thumbnail": "sha256-ea44cae9ff01f902269d1c5b419b22f6405a02b0e0d434e7814b6761444fda01",
    "createdAt": "2019-06-06 15:10:25.471+00"
  }
]

User is not authenticated. They must be authenticated to use this service.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

No configuration was found with the given ID or short ID.

{
  "error": {
    "code": "configuration_not_found",
    "message": "Configuration not found"
  }
}

Retrieves the thumbnail of a configuration from its ID or shortID.

Retrieves a thumbnail from its ID or shortID.

REST Endpoint

GET https://admin.threekit.com/api/configurations/{id}/thumbnail?bearertoken=[bearertoken]

Query Parameters

Name	In	Type	Required	Description
id	path	string	true	ID or shortID of the configuration whose thumbnail needs to be retrieved.
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.

Responses

Status	Meaning	Description	Schema
200	OK	none	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
404	Not Found	Either the configuration or the thumbnail was not found	None

Examples

Code

CURL

curl --request GET \
  --url https://admin.threekit.com/api/configurations/string/thumbnail \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/configurations/string/thumbnail",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/configurations/string/thumbnail",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

User is not authenticated. They must be authenticated to use this service.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

Either the configuration or the thumbnail was not found

{
  "error": {
    "code": "configuration_not_found",
    "message": "Configuration not found"
  }
}

{
  "error": {
    "code": "thumbnail_no_found",
    "message": "No thumbnail exists for this configuration"
  }
}

Schemas

configurationBody

{
  "orgId": "7f6a52b7-a10b-4945-836a-5fecc24ee914",
  "productId": "e5d536ec-e89c-46fc-8773-7e54ba70517a",
  "productVersion": "exampleVersionNumber",
  "variant": {
    "ExampleVariantField1": "ExampleValue1"
  },
  "metadata": {
    "SKU": "exampleSKU"
  },
  "files": "string",
  "shortId": "46Juzcyx",
  "customerId": "bba8a2d8-528e-4a20-beea-bc59f7863dcb"
}

Properties

Name	Type	Required	Restrictions	Description
orgId	string	false	none	Organization ID
productId	string	true	none	ID of the product
productVersion	string	true	none	Version of the product
variant	object	false	none	Configuration variant information (If present). This refers to the product attributes and their values for the configuration in question.
metadata	object	false	none	Metadata information associated with the configuration (If present)
files	string(binary)	false	none	An image or a thumbnail of the configured product. NOTE --- This parameter will only accept a file.
shortId	string	false	none	Automatically generated shortID. It can be used in place of the id field
customerId	string	false	none	Customer ID

Menu

Articles in this section

In this article

Saves a configuration.

REST Endpoint

Query Parameters

Body Parameters

Responses

Examples

Code

CURL

Node.JS

PHP

Example responses

200 Response

User is not authenticated. They must be authenticated to use this service.

User is authenticated but lacks authorization to use this service

The configuration information provided in the request is missing mandatory fields

Retrieves a list of configurations.

REST Endpoint

Query Parameters

Responses

Examples

Code

CURL

Node.JS

PHP

Example responses

Successful GET request. Response body will include list of configurations.

User is not authenticated. They must be authenticated to use this service.

User is authenticated but lacks authorization to use this service

No configurations exist in the database, based on the query parameter(s) provided.

Retrieves a list of configurations by SKU.

REST Endpoint

Query Parameters

Responses

Examples

Code

CURL

Node.JS

PHP

Example responses

Successful GET request. Response body will include list of configurations.

User is not authenticated. They must be authenticated to use this service.

SKU was not passed

Retrieves a configuration from its ID or shortID.

REST Endpoint

Query Parameters

Responses

Examples

Code

CURL

Node.JS

PHP

Example responses

Successful GET request, retrieving a configuration using its ID or short ID.

User is not authenticated. They must be authenticated to use this service.

No configuration was found with the given ID or short ID.

Retrieves the thumbnail of a configuration from its ID or shortID.

REST Endpoint

Query Parameters

Responses

Examples

Code

CURL

Node.JS

PHP

Example responses

User is not authenticated. They must be authenticated to use this service.

Either the configuration or the thumbnail was not found

Schemas

configurationBody

Properties

Related articles