VNTANA Logo - White
Book a Call
Get Started Free

Resources

VNTANA Resource API – Integration Attributes

API – Integration Attributes

API Base URL: https://api-platform.vntana.com

For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.

Integrations allow users to better manage their 3D assets between VNTANA and whatever destination they have for these assets. VNTANA currently offers API access to data for the following integrations:

  • Amazon
  • Shopify

Integration Attributes behave similarly to attributes in that they are <key>:<value> pairs of data stored on an individual Asset. Unlike regular attributes, they are handled separately and do not interact with the regular Asset creation or update flows. Additionally, there while regular attributes are open-ended and can be any <key>, integration attributes are limited to specific <key>’s based on the current available integrations.

Creating or Updating Integration Attributes

To create or update integration attributes on an Asset, you can call a single PUT endpoint. Unlike Asset creation/editing the method doesn’t change depending on whether you are creating or updating, it will always be a PUT request. The behavior is instead determined by the parameters that are passed in the request body. The following endpoint allows you to set integrationAttributes:
1
2
3
4
5
6
7
8
9
10
11
12
Method: PUT
Endpoint: /v1/products/integration-attributes
Headers: { x-auth-token : ‘Bearer ‘ + refreshToken }
Body: {
‘productUuid’ : ‘string’,
‘type’ : ‘string’, // AMAZON or SHOPIFY
‘attributes’ : {
// <key>:<value> pairs depend on the data you are setting, but must be
// from specific fields
},
‘operationType’ : ‘string’ // ADD or REPLACE
}

  • productUuid – [REQUIRED] The UUID of the Asset to update.

  • type – [REQUIRED] The type of integration, can be AMAZON or SHOPIFY.

  • operationType – [REQUIRED] Indicates how to handle the data, can be ADD or REPLACE.

    • ADD will simply ‘append’ the data to the Asset’s integrationAttributes. This means that it will persist what was previously stored on the Asset’s integrationsAttributes, so if you only pass asins no other data will be lost.

    • REPLACE will first clear the integrationAttributes on an Asset and then populate it with only what is passed in the new request.

  • attributes – [REQUIRED] The <key>:<values> to set. While the attributes field is required, the contents are fluid and can be from the following:

    • asins – Object containing <key>:<value> pairs of Amazon marketplaceId’s and Amazon Product Asins. Ex: “ATVPDKIKX0DER":"B000000000". Note: the marketplaceId refers to an Amazon Store such as United States, Canada, etc.

    • dimensions – While this data is required for publishing to Amazon, it is optional in this request and we recommend using the generated dimensions on Platform, found in the Amazon Integration tab of an individual Asset. Object containing the following:

      • unit – Can be CENTIMETERS or METERS

      • length

      • width

      • height

    • productName – Shopify Product name, only used by the VNTANA App for Shopify

    • productId – Shopify Product ID, only used by the VNTANA App for Shopify

A successful request will return the current data stored on an Asset’s integrationAttributes field in the response body. A note on the response, there will be two UUID’s return: uuid and originProductUuid. The originalProductUuid refers to the Asset UUID passed in the request as productUuid, while uuid is just a UUID to identify the request.

An example request to create Amazon integration attributes on an asset:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“productUuid”: “string”,
“type”: “AMAZON”,
“attributes”: {
“asins”: {
“ATVPDKIKX0DER”: “B000000000”,
“A1RKKUPIHCS9HS”: “B000000000”
},
“dimensions”: {
“unit”: “CENTIMETERS”,
“length”: 32.20,
“width”: 21.69,
“height”: 11.40
}
},
“operationType”: “ADD”
}

with the following example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
“success”: true,
“errors”: [],
“response”: {
“uuid”: “string”,
“organizationUuid”: “string”,
“originProductUuid”: “string”,
“type”: “AMAZON”,
“attributes”: {
“asins”: {
“ATVPDKIKX0DER”: “B000000000”,
“A1RKKUPIHCS9HS”: “B000000000”
},
“type”: “AMAZON”,
“dimensions”: {
“unit”: “CENTIMETERS”,
“length”: 32.2,
“width”: 21.69,
“height”: 11.4
}
}
}
}
Possible Error Codes

MISSING_PRODUCT_UUID

  • Returned if the request body does not contain the productUuid parameter.

MISSING_INTEGRATION_TYPE

  • Returned if the request body does not contain the type parameter.

MISSING_INTEGRATION_ATTRIBUTES

  • Returned if the request body does not contain the attributes parameter.

INVALID_INTEGRATION_ATTRIBUTE_KEY

  • Returned if a <key> is used in the attribtues parameter that isn’t recognized as an integrationAttribute.

ORIGIN_PRODUCT_NOT_FOUND

  • Returned if the productUuid refers to an invalid Asset. Likely caused by the deletion or moving of an Asset, or just a typo.

INVALID_ATTRIBUTE_VALUE

  • Returned if the value of an attribute <key> is invalid, i.e. passing a list as the value for productName.

Retrieving List of Amazon Marketplace IDs

When adding integration attributes to Assets for the Amazon Integration, as well as publishing an Asset to Amazon, you will need the marketplaceId of each marketplace the Asset should be published to. To get a full list of every market place you can call the following endpoint:

1
2
3
Method: GET
Endpoint: /v1/integration-settings/amazon-marketplaces/{SELLER or VENDOR}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
This will return a list of each marketplace with code representing the marketplaceId and description refers to the name of the marketplace that you would see on the platform when linking. Alternatively, if you just wish to grab the ID(s) you need the full list is below.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 22,
“grid”: [
{
“region”: “NORTH_AMERICA”,
“code”: “A2EUQ1WTGCTBG2”,
“description”: “Canada”,
“countryCode”: “CA”,
“oauthURL”: “”,
“storeURL”: “amazon.ca”
},
{
“region”: “NORTH_AMERICA”,
“code”: “A1AM78C64UM0Y8”,
“description”: “Mexico”,
“countryCode”: “MX”,
“oauthURL”: “”,
“storeURL”: “amazon.com.mx”
},
{
“region”: “NORTH_AMERICA”,
“code”: “A2Q3Y263D00KWC”,
“description”: “Brazil”,
“countryCode”: “BR”,
“oauthURL”: “”,
“storeURL”: “amazon.com.br”
},
{
“region”: “EUROPE”,
“code”: “A1RKKUPIHCS9HS”,
“description”: “Spain”,
“countryCode”: “ES”,
“oauthURL”: “”,
“storeURL”: “amazon.es”
},
{
“region”: “EUROPE”,
“code”: “A1F83G8C2ARO7P”,
“description”: “United Kingdom”,
“countryCode”: “UK”,
“oauthURL”: “”,
“storeURL”: “amazon.co.uk”
},
{
“region”: “EUROPE”,
“code”: “A13V1IB3VIYZZH”,
“description”: “France”,
“countryCode”: “FR”,
“oauthURL”: “”,
“storeURL”: “amazon.fr”
},
{
“region”: “NORTH_AMERICA”,
“code”: “ATVPDKIKX0DER”,
“description”: “United States”,
“countryCode”: “US”,
“oauthURL”: “”,
“storeURL”: “amazon.com”
},
{
“region”: “EUROPE”,
“code”: “A1805IZSGTT6HS”,
“description”: “Netherlands”,
“countryCode”: “NL”,
“oauthURL”: “”,
“storeURL”: “amazon.nl”
},
{
“region”: “EUROPE”,
“code”: “A1PA6795UKMFR9”,
“description”: “Germany”,
“countryCode”: “DE”,
“oauthURL”: “”,
“storeURL”: “amazon.de”
},
{
“region”: “EUROPE”,
“code”: “APJ6JRA9NG5V4”,
“description”: “Italy”,
“countryCode”: “IT”,
“oauthURL”: “”,
“storeURL”: “amazon.it”
},
{
“region”: “EUROPE”,
“code”: “A2NODRKZP88ZB9”,
“description”: “Sweden”,
“countryCode”: “SE”,
“oauthURL”: “”,
“storeURL”: “amazon.se”
},
{
“region”: “EUROPE”,
“code”: “AE08WJ6YKNBMC”,
“description”: “South Africa”,
“countryCode”: “ZA”,
“oauthURL”: “”,
“storeURL”: “amazon.co.za”
},
{
“region”: “EUROPE”,
“code”: “A1C3SOZRARQ6R3”,
“description”: “Poland”,
“countryCode”: “PL”,
“oauthURL”: “”,
“storeURL”: “amazon.pl”
},
{
“region”: “EUROPE”,
“code”: “ARBP9OOSHTCHU”,
“description”: “Egypt”,
“countryCode”: “EG”,
“oauthURL”: “”,
“storeURL”: “amazon.eg”
},
{
“region”: “EUROPE”,
“code”: “A33AVAJ2PDY3EV”,
“description”: “Turkey”,
“countryCode”: “TR”,
“oauthURL”: “”,
“storeURL”: “amazon.com.tr”
},
{
“region”: “EUROPE”,
“code”: “A17E79C6D8DWNP”,
“description”: “Saudi Arabia”,
“countryCode”: “SA”,
“oauthURL”: “”,
“storeURL”: “amazon.sa”
},
{
“region”: “EUROPE”,
“code”: “A2VIGQ35RCS4UG”,
“description”: “United Arab Emirates”,
“countryCode”: “AE”,
“oauthURL”: “”,
“storeURL”: “amazon.ae”
},
{
“region”: “EUROPE”,
“code”: “A21TJRUUN4KGV”,
“description”: “India”,
“countryCode”: “IN”,
“oauthURL”: “”,
“storeURL”: “amazon.in”
},
{
“region”: “EUROPE”,
“code”: “AMEN7PMS3EDWL”,
“description”: “Belgium”,
“countryCode”: “BE”,
“oauthURL”: “”,
“storeURL”: “amazon.com.be”
},
{
“region”: “FAR_EAST”,
“code”: “A19VAU5U5O7RUS”,
“description”: “Singapore”,
“countryCode”: “SG”,
“oauthURL”: “”,
“storeURL”: “amazon.sg”
},
{
“region”: “FAR_EAST”,
“code”: “A39IBJ37TRP1C6”,
“description”: “Australia”,
“countryCode”: “AU”,
“oauthURL”: “”,
“storeURL”: “amazon.com.au”
},
{
“region”: “FAR_EAST”,
“code”: “A1VC38T7YXB528”,
“description”: “Japan”,
“countryCode”: “JP”,
“oauthURL”: “”,
“storeURL”: “amazon.co.jp”
}
]
}
}

Retrieving Integration Attributes for An Asset

There are two options for retrieving the integrationAttributes for an asset, where one allows you to filter the response by the integration type.
Retrieve Integration Attributes by Type
To retrieve a specific integrationsintegrationAttributes for an Asset, call the following endpoint:
1
2
3
Method: GET
Endpoint: /v1/products/integration-attributes/{type}/{productUuid}
Headers: { x-auth-token : ‘Bearer ‘ + refreshToken }

Where type can be either AMAZON or SHOPIFY. For the AMAZON type, only asins for marketplaceId’s that are enabled in the organization will be returned. An example of a response can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
“success”: true,
“errors”: [],
“response”: {
“uuid”: null,
“organizationUuid”: “string”,
“originProductUuid”: “string”,
“type”: “AMAZON”,
“attributes”: {
“asins”: {
“A1AM78C64UM0Y8”: null,
“ATVPDKIKX0DER”: “B000000000”
},
“marketplaces”: [
 
{
“asin”: “B09ZPYHQM9”,
“region”: “NORTH_AMERICA”,
“code”: “ATVPDKIKX0DER”,
“description”: “United States of America”,
“countryCode”: “US”,
“oauthURL”: “”,
“storeURL”: “amazon.com”
},
{
“asin”: null,
“region”: “NORTH_AMERICA”,
“code”: “A1AM78C64UM0Y8”,
“description”: “Mexico”,
“countryCode”: “MX”,
“oauthURL”: “”,
“storeURL”: “amazon.com.mx”
}
],
“type”: “AMAZON”,
“dimensions”: {
“unit”: “CENTIMETERS”,
“length”: 32.2,
“width”: 21.69,
“height”: 11.4
}
}
}
}
If a particular marketplaceId hasn’t been assigned an asin for an asset, it’ll just return null for its value.
Possible Error Codes

INTEGRATION_ATTRIBUTES_NOT_FOUND

  • Indicates this asset does not have any integrationAttributes for that type.

Retrieving All Integration Attributes for an Asset
To retrieve all the integrationAttributes for an Asset, regardless of type, use the following endpoint:
1
2
3
Method: GET
Endpoint: /v1/products/integration-attributes/{productUuid}
Headers: { x-auth-token : ‘Bearer ‘ + refreshToken }
Unlike the previous endpoint, this will return the integrationAttributes as a list under the <key> grid (see sample response below). Each element of the list will pertain to an integration type. As with the other endpoint, for AMAZON data, only asins for marketplaceId’s that the organization have added will be returned.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 2,
“grid”: [
{
“uuid”: “”,
“organizationUuid”: “”,
“originProductUuid”: “”,
“type”: “AMAZON”,
“attributes”: {
“asins”: {
“ATVPDKIKX0DER”: “B000000000”,
“A1RKKUPIHCS9HS”: “B000000000”
},
“type”: “AMAZON”,
“dimensions”: {
“unit”: “CENTIMETERS”,
“length”: 32.2,
“width”: 21.69,
“height”: 11.4
}
}
},
{
“uuid”: “”,
“organizationUuid”: “”,
“originProductUuid”: “”,
“type”: “SHOPIFY”,
“attributes”: {
“productId”: “abcd1234”,
“productName”: “front-door”
}
}
]
}
}

Amazon Integration - Publishing

It is possible to publish your Assets to Amazon via the API once the required integrationAttributes are set. This can be done using a single or bulk endpoint. It is important to note that assets will fail to publish if they do not have at least one asin assigned to a connected store, and values for the dimensions.

Note: To publish to Amazon, an Asset must be in the Live Public state and cannot be currently processing.

To publish a single asset via the API, call the following endpoint:

1
2
3
4
5
6
7
8
9
10
Method: POST
Endpoint: /v1/products/integration/publish
Headers: { x-auth-token : ‘Bearer ‘ + refreshToken }
Body: {
‘productUuid’ : ‘string’,
‘publishTo’ : ‘AMAZON’,
‘marketplaceIds’ : [
‘ATVPDKIKX0DER’
]
}

  • productUuid – [REQUIRED] The UUID of the Asset to publish to Amazon

  • publishTo – [REQUIRED] Indicates the integration type this publish action corresponds to. Currently only Amazon utilizes this functionality.

  • marketplaceIds – [REQUIRE] List of IDs for the Amazon stores to publish to. These must have already been connected to the Organization via the Integrations settings on Platform.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“originProductUuid”: “”,
“marketplaceId”: “ATVPDKIKX0DER”,
“uuid”: “”
}
]
}
}

The bulk endpoint is slightly altered:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Method: POST
Endpoint: /v1/products/integration/bulk/publish
Headers: { x-auth-token : ‘Bearer ‘ + refreshToken }
Body: {
“productUuids”: [
“”,
“”
],
“publishTo”: “AMAZON”,
“marketplaceIds”: [
“ATVPDKIKX0DER”
],
“ignoreInvalidProducts”: true
}

The only two differences (aside from the different endpoint) are the following:

  • productUuids – [REQUIRED] A list of all productUuid’s to publish.

  • ignoreInvalidProducts – [REQUIRED] Indicates whether the operation should simply skip Assets that are missing required data and publish the rest or exit early.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 2,
“grid”: [
{
“uuid”: null,
“originProductUuid”: “”
},
{
“uuid”: null,
“originProductUuid”: “”
}
]
}
}
The primary difference in the two endpoints responses is that marketplaceId isn’t returned for the individual grid elements.
Possible Error Codes

These error codes can be returned for either the single or bulk operation, however note that if ignoreInvalidProducts is set to true some of these may not be triggered on the bulk operation.

MISSING_PRODUCT_UUID

  • No productUuid is provided / productUuids is empty.

MISSING_PUBLISH_TO

  • publishTo parameter is missing or it’s value is invalid.

MISSING_MARKETPLACE_IDS

  • No valid marketplaceIds are provided.

PRODUCT_MUST_BE_LIVE_PUBLIC

  • An Asset you are trying to publish is not in the Live Public state.

ORIGIN_PRODUCT_NOT_FOUND

  • A provided productUuid is invalid, either because the Asset has been moved or deleted (or there is a typo).

PRODUCT_IN_PROCESSING_STATUS

  • An asset provided is currently in the optimization process.

MISSING_GLB_MODEL

  • An asset provided does not have an optimized GLB format available.

MISSING_INTEGRATION_ATTRIBUTES

MISSING_INTEGRATION_ATTRIBUTE_DIMENSIONS

MISSING_INTEGRATION_ATTRIBUTE_ASIN

Each of the preceding three refer to missing data required for publishing.

Integration Status

In addition to the manipulation and retrieval of integrationAttributes, it is also possible to check the status of publishing by checking the integrationStatus parameter. This value will be returned with the Asset data retrieved using the search endpoints below:

  • /v1/products/clients/search

  • /v1/products/clients/{clientUuid}/search

The data returned will contain the following:

1
2
3
“integrationsStatus”: {
“AMAZON”: “REMOTE_FAILED”
}

This status is an aggregated status for the Asset, with more weight placed on error states. This means that if an asset was published to the Canada and United States stores and both have the status REMOTE_FAILED, the returned status would be REMOTE_FAILED. The possible states are:

  • LOCAL_CREATED, LOCAL_ERROR, REMOTE_CREATED, REMOTE_UPDATED, REMOTE_PROCESSING, REMOTE_COMPLETED, REMOTE_FAILED, REMOTE_REJECTED, REMOTE_ERROR

To see the full context of the response for these endpoints, see the guide on Searching Assets.

In order to see the individual marketplace statuses, you can call the following endpoint:

1
2
3
Method: GET
Endpoint: /v1/products/integration-uploads/{type}/{productUuid}?marketPlaceId={marketPlaceId}
Headers: { x-auth-token : ‘Bearer ‘ + refreshToken }
The allowed types are AMAZON and SHOPIFY, however only Amazon will return data. The marketPlaceId is optional, excluding it will simply return the status for all linked marketplaces in the organization for that Asset.

This endpoint will return the following response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uploadDate”: null,
“lastStatusChange”: null,
“uuid”: “”,
“organizationUuid”: “”,
“productUuid”: “”,
“externalUploadId”: “”,
“externalProductId”: “B000000000”,
“externalIdType”: “ASIN”,
“marketPlaceId”: “ATVPDKIKX0DER”,
“type”: “AMAZON”,
“status”: “REMOTE_FAILED”,
“requiredActions”: [
“missing-reference-image-from-detailed-page”
],
“externalReportUrl”: null
}
]
}
}
The grid will contain an object for each marketPlaceId if the query parameter is left out of the request.

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.
Learn More

Tap the magnifying glass to the left of your screen to search our resources.

OK