Documentation for the API
Below we describe which fields are necessary for the integration to be carried out successfully. The field names don't necessarily have to be the same, but it's important that the api returns all or most of them.
This page describes the response of your API's product detail endpoint, this endpoint should receive the product unique identifier as a parameter, and return only one product.
If your api needs more than one request to deliver all the information, this generates a longer response time and increases the complexity of the integration.
| Property | Format | Details |
|---|---|---|
| id | Required Your product’s unique identifier Example C8DAF871-7E4D-460E-8D7F-DB39A1861635 Syntax Max 50 characters | Use a unique value for each product Use only valid unicode characters. Avoid invalid characters like control, function, or private area characters |
| sku | Required Product’s unique identifier Example 0000000 Syntax Max 50 characters | Use product's SKU where possible, or use a unique value for each product and variation Use only valid unicode characters. Avoid invalid characters like control, function, or private area characters |
| name | Required Your product’s name Example Mens Pique Polo Shirt Syntax Max 150 characters | Accurately describe your product Don’t include promotional text like "free shipping," all capital letters, or gimmicky foreign characters |
| description | Required Your product’s description Example Made from 100% organic cotton, this classic red men’s polo has a slim fit and signature logo embroidered on the left chest. Machine wash cold; imported. Syntax Max 5000 characters | Accurately describe your product Don’t include promotional text like "free shipping," all capital letters, or gimmicky foreign characters Include only information about the product. Don’t include links to your store, sales information, details about competitors, other products, or accessories Use HTML for formatting (for example, line breaks, lists, or italics) to format your description |
| price | Required Your product’s price Example 15.00 Syntax Numeric | Accurately submit the product's price and currency, and match with the price from your landing page and at checkout Make sure that your checkout pages include the price in the currency of the country of sale prominently |
| salePrice | Optional Your product's sale price Example 15.00 Syntax Numeric | Meet the requirements for the price attribute Submit the salePrice in addition to the price attribute with the non-sale price |
| images | Required The URL of your product’s image list Example [http://www.example.com/image1.jpg] Syntax Array of strings | For the image URL: Link to the main image of your product Start with http or https Use an encoded URL that complies with RFC 2396 or RFC 1738. For example, a comma would be represented as "%2C" For the image: Accurately display the product you're selling Use an accepted format: JPEG (.jpg/.jpeg), WebP (.webp), PNG (.png), non-animated GIF (.gif), BMP (.bmp), and TIFF (.tif/.tiff) Use an image of at least 150 x 150 pixels Don't submit a file larger than 2MB Don't scale up an image or submit a thumbnail Don't include promotional text, watermarks, or borders |
| variationsForm | Optional Your product's variations and options This will be used to display the product's variations form Syntax VariationFormObject[] | See VariationFormObject's documentation below |
| items | Optional Your product's variants SKUs Syntax ProductItemObject[] | See ProductItemObject's documentation below |
| availableQuantity | Optional Your product’s avalable quantity Example 10 Syntax Numeric | If value is null, the shop will make this product available. |
| Property | Format | Details |
|---|---|---|
| name | Required Your variation's name Example Color Syntax Max 50 characters | Accurately describe your variation Don’t include promotional text like "free shipping," all capital letters, or gimmicky foreign characters |
| options | Required Your variation's options Example ["Red", "Green", "Blue"] Syntax Max 50 characters per option Array of strings | Accurately describe your option |
ProductItemObject
| Property | Format | Details |
|---|---|---|
| id | Required Your product’s unique identifier Example C8DAF871-7E4D-460E-8D7F-DB39A1861635 Syntax Max 50 characters | Use a unique value for each product Use only valid unicode characters. Avoid invalid characters like control, function, or private area characters |
| sku | Required Product’s unique identifier Example 0000000 Syntax Max 50 characters | Use product's SKU where possible, or use a unique value for each product and variation Use only valid unicode characters. Avoid invalid characters like control, function, or private area characters |
| name | Required Your product’s name Example Mens Pique Polo Shirt Syntax Max 150 characters | Accurately describe your product Don’t include promotional text like "free shipping," all capital letters, or gimmicky foreign characters Include a distinguishing feature such as color or size |
| description | Required Your product’s description Example Made from 100% organic cotton, this classic red men’s polo has a slim fit and signature logo embroidered on the left chest. Machine wash cold; imported. Syntax Max 5000 characters | Accurately describe your product Don’t include promotional text like "free shipping," all capital letters, or gimmicky foreign characters Include only information about the product. Don’t include links to your store, sales information, details about competitors, other products, or accessories Use HTML for formatting (for example, line breaks, lists, or italics) to format your description |
| price | Required Your product’s price Example 15.00 Syntax Numeric | Accurately submit the product's price and currency, and match with the price from your landing page and at checkout Make sure that your checkout pages include the price in the currency of the country of sale prominently |
| salePrice | Optional Your product's sale price Example 15.00 Syntax Numeric | Meet the requirements for the price attribute Submit the salePrice in addition to the price attribute with the non-sale price |
| images | Required The URL of your product’s image list Example [http://www.example.com/image1.jpg] Syntax Array of strings | For the image URL: Link to the main image of your product Start with http or https Use an encoded URL that complies with RFC 2396 or RFC 1738. For example, a comma would be represented as "%2C" For the image: Accurately display the product you're selling Use an accepted format: JPEG (.jpg/.jpeg), WebP (.webp), PNG (.png), non-animated GIF (.gif), BMP (.bmp), and TIFF (.tif/.tiff) Use an image of at least 150 x 150 pixels Don't submit a file larger than 2MB Don't scale up an image or submit a thumbnail Don't include promotional text, watermarks, or borders |
| availableQuantity | Optional Your product’s avalable quantity Example 10 Syntax Numeric | If value is null, the shop will make this product available. |
| variations | Required Your product's variations definitions Example [ { "key": "Color", "value": "Red" }, { "key": "size", "value": "M" } ] Syntax VariationObject[] | See VariationObject's documentation below |
| Property | Format | Details |
|---|---|---|
| key | Required The name of variation that matches the item Example Color Syntax Max 50 characters | |
| value | Required The value of variation that matches the item Example Red Syntax Max 50 characters |
{
"id": "C8DAF871-7E4D-460E-8D7F-DB39A1861635",
"sku": "0000000",
"name": "Mens Pique Polo Shirt",
"description": "Made from 100% organic cotton, this classic red men’s polo has a slim fit and signature logo embroidered on the left chest. Machine wash cold; imported.",
"price": 89.90,
"salePrice": 69.90,
"images": [
"http://www.example.com/image1.jpg"
],
"variationsForm": [{
"name": "Color",
"options": ["Red", "Green", "Blue"]
},
{
"name": "Size",
"options": ["M"]
}
],
"items": [{
"id": "34EEB6E9-427A-4CF7-9104-EB7F745765F8",
"sku": "0000001",
"name": "Mens Pique Polo Shirt - Red - M",
"price": 89.9,
"salePrice": 69.90,
"variations": [{
"key": "Color",
"value": "Red"
}, {
"key": "Size",
"value": "M"
}]
}, {
"id": "36016806-E82F-48AE-BC31-75C5D8907AB1",
"sku": "0000002",
"name": "Mens Pique Polo Shirt - Green - M",
"price": 89.9,
"salePrice": 69.90,
"variations": [{
"key": "Color",
"value": "Green"
}, {
"key": "Size",
"value": "M"
}]
}, {
"id": "5B72B7FA-D157-474F-9EA8-65210F68FDA4",
"sku": "0000003",
"name": "Mens Pique Polo Shirt - Blue - M",
"price": 89.9,
"salePrice": 69.90,
"variations": [{
"key": "Color",
"value": "Blue"
}, {
"key": "Size",
"value": "M"
}]
}]
}