productBulkUpload.html - alexistaylor-cocacola/Seller-API-Documentation Wiki


Home > Product Catalog > Product Bulk Upload


Product Bulk Upload API details for sellers

This is an API used to upload a large list of products you want to update. You can send it in either json or csv format, and in response you will receive a callback code to use with a get call. You may poll for results using the callback code in the GET call, and once your request is finished processing, you will be able to check your results using a URL received from the GET call response.

This API works like a bulk form of the Offer Products For Sale API.

This page describes how sellers may utilize the product bulk upload API to upload a large quantity of product information.


Request

Sandbox: https://sandbox.sellerapi.mywabi2b.com/v1/offerProductsForSaleBulkUpload
Production: https://sellerapi.mywabi2b.com/v1/offerProductsForSaleBulkUpload

Maximum 1000 products can be provided at once. All calls to this API are throttled at max 750 calls per 5 minutes and max 15,000 calls in 24 hours per seller.

You must send an Authorization header containing a JWT token which will be used for authentication purposes. You will obtain this JWT token from the Authenticate API. For more details, see the authentication page.
The name of the Authorization header must be Authorization.

You must also send a "format" header to indicate which format you are sending. Valid values are "csv" or "json", representing a csv or json payload respectively. You should additionally update your Content-Type header to "text/csv" or "application/json" respectively.

You must also provide an x-api-key on a header which will be given to you during onboarding.

Request Payload Fields

Field Name Data Type Description
product string The gtin of the product. Should be a 14 digit number.
productName string The name of the product. Cannot exceed 80 characters or contain a line break.
productDescription string The description of the product. Cannot exceed 80 characters or contain a line break.
brand string The product's brand. Cannot exceed 255 characters or contain a line break.
category string The product's category. Must be an existing category.
specs array Array of product specs in name-value pairs. Optional.
media array Array of product media, in type-url pairs. At least one "Product Image" is required.

You must provide an image of type "Product Image" in the product media, or your request will fail. This image must have at least one side longer than 260px. You will provide the URL of this image, which will be downloaded, resized appropriately, and a cached version will be used on Wabi's site.
You can also provide images of type "Product Search Image" and "Product Image Thumbnail". These images must have at least one side longer than 160px. You would provide the URL of either image, which would be downloaded, resized appropriately, and a cached version would be used on Wabi's site. If they are not provided, the Product Image will be used to create them.
You cannot provide two images of the same type or your request will fail.

For the "category" field, you must provide an existing category. See the List Categories page to learn how to receive a list of existing categories. If you do not provide an existing category, your request will not be successful.

The specs describe various specifications about the product. You may use the List Suggested Spec Names page to learn how to receive a list of existing spec names for your reference. Unlike categories, you do not have to only use existing spec names. However, bear in mind that any new spec names will be subject to an approval process. Specs are optional and you do not have to include them.

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Product Bulk Upload Request Payload",
    "description": "The payload for a Product Bulk Upload post request",
    "type": "array",
    "items": {
        "type": "object",
        "description": "Product information",
        "required": ["product", "productName", "productDescription", "brand", "category", "media"],

        "properties": {
            "product": {
                "description": "The gtin of the product. Should be a 14 digit number.",
                "type": "string",
                "minLength": 14,
                "maxLength": 14
            },
            "productName": {
                "description": "The name of the product. Cannot exceed 80 characters or contain a line break.",
                "type": "string",
                "maxLength": 80
            },
            "productDescription": {
                "description": "The description of the product. Cannot exceed 80 characters or contain a line break.",
                "type": "string",
                "maxLength": 80
            },
            "brand": {
                "description": "The product's brand. Cannot exceed 255 characters or contain a line break.",
                "type": "string",
                "maxLength": 255
            },
            "category": {
                "description": "The product's category. Must be an existing category.",
                "type": "string"
            },
            "specs": {
                "description": "Array of product specs in name-value pairs.",
                "type": "array",
                "items": { "$ref": "#/$defs/spec" }
            },
            "media": {
                "description": "Array of product media, in type-url pairs.",
                "type": "array",
                "items": { "$ref": "#/$defs/media" },
                "minItems": 1
            }
        }
    },

    "$defs": {
        "spec": {
            "type": "object",
            "description": "A name-value pair describing a spec.",
            "required": ["name", "value"],

            "properties": {
                "name": {
                    "description": "The name of the spec.",
                    "type": "string"
                }, 
                "value": {
                    "description": "The value of the spec.",
                    "type": "string"
                }
            }
        },
        "media": {
            "type": "object",
            "description": "A type-url pair describing a product media.",
            "required": ["type", "url"],

            "properties": {
                "type": {
                    "description": "The type of the media.",
                    "type": "string",
                    "enum": ["Product Image", "Product Search Image", "Product Image Thumbnail"]
                },
                "url": {
                    "description": "The url of the product media.",
                    "type": "string"
                }
            }
        }
    }
}

Example JSON Request Payload:

Headers:
Authorization: jwtTokenHere
x-api-key: keyGoesHere
format: json
Content-Type: application/json

[
    {
        "product": "00025000040296",
        "productName": "Magic Chips",
        "productDescription": "Chips so good, they're magical!",
        "brand": "Super Chips Co",
        "category": "Snacks & Chips",
        "specs": [
            {
                "name": "Unit Of Measure",
                "value": "oz"
            },
            {
                "name": "Unit Size",
                "value": "12"
            }
        ],
        "media": [
            {
                "type": "Product Image",
                "url": "https://cep-images.coke.com/en_US/ProductImage/700373-00P4w000019FdqxEAC.jpg"
            }
        ]
    },
    {
        "product": "01050668000408", 
        "productName": "Deep River Kettle Original Salted",
        "productDescription": "Deep River Kettle Original Salted, 2 Oz, 24 Pack",
        "brand": "Deep River",
        "category": "Snacks & Chips",
        "media": [
            {
                "type": "Product Image",
                "url": "https://cep-images.coke.com/en_US/ProductImage/700373-00P4w000019FdqxEAC.jpg"
            },
            {
                "type": "Product Image Thumbnail",
                "url": "https://cep-images.coke.com/en_US/ProductImageThumbnail/700373-00P4w000019FdrGEAS.jpg"
            }
        ],
        "specs": [
            {
                "name": "Brands_en_US",
                "value": "Deep River"
            },
            {
                "name": "Unit Size_en_US",
                "value": "2 oz"
            },
            {
                "name": "Case Qty_en_US",
                "value": "24"
            },
            {
                "name": "Flavor_en_US",
                "value": "Salted"
            },
            {
                "name": "Calories_en_US",
                "value": "Regular Calorie"
            },
            {
                "name": "Package Type_en_US",
                "value": "Pouch/Bag"
            }
        ]
    }
]

Example CSV Request Payload:

Headers:
Authorization: jwtTokenHere
x-api-key: keyGoesHere
format: csv
Content-Type: text/csv

product,productName,productDescription,brand,category,media1-url,media1-type,media2-url,media2-type,media3-url,media3-type,spec1-name,spec1-value,spec2-name,spec2-value,spec3-name,spec3-value,spec4-name,spec4-value,spec5-name,spec5-value
00025000040296,Magic Chips,Chips so good they're magical!,Super Chips Co,Chips & Snacks,https://sandbox.productimages.mywabi2b.com/images/40000000000001/63f9b922f7f3fd2005c493e4263459ac/20220627230124326/ProductImage.jpg,Product Image,https://sandbox.productimages.mywabi2b.com/images/40000000000001/63f9b922f7f3fd2005c493e4263459ac/20220627230124326/ProductImageThumbnail.jpg,Product Image Thumbnail,https://sandbox.productimages.mywabi2b.com/images/40000000000001/63f9b922f7f3fd2005c493e4263459ac/20220627230124326/ProductSearchImage.jpg,Product Search Image,Unit of Measure,oz,Unit Size,12,,,,,,

POST Response

The POST response payload is a callback code. This can be passed on a GET call to poll for results. The process to do this is detailed below.

Response Payload Fields

Field Name Data Type Description
callBackCode string A callback code to use in a GET call to poll for results

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Product Bulk Download Post Response Payload",
    "description": "The payload for a Product Bulk Download post response",
    "type": "object",
    "required": [],
    
    "properties": {
        "callBackCode": {
            "description": "A callback code to use in a GET call to poll for results",
            "type": "string"
        }
    }
}

Example Response Payload:

{
    "callBackCode": "bf41e1a4656ff069512249b5bac13c17d702d7e0"
}

GET Request

Sandbox: https://sandbox.sellerapi.mywabi2b.com/v1/listProductsBulkDownload
Production: https://sellerapi.mywabi2b.com/v1/listProductsBulkDownload

The get request can be used by passing the callBackCode obtained from the POST call on a URL parameter. It will respond with status information and results.

You must send an Authorization header containing a JWT token which will be used for authentication purposes. You will obtain this JWT token from the Authenticate API. For more details, see the authentication page.
The name of the Authorization header must be Authorization.

You must also provide an x-api-key on a header which will be given to you during onboarding.

Request Parameters

Param Name Description
callBackCode The callback code received from the POST request

Example GET Request Call:

Headers:
Authorization: jwtTokenHere
x-api-key: keyGoesHere

https://sandbox.sellerapi.mywabi2b.com/v1/offerProductsForSaleBulkUpload?callBackCode=bf41e1a4656ff069512249b5bac13c17d702d7e0

GET Response

The URL given in s3Path will tell you the status of your request in greater detail.

Response Payload Fields

Field Name Data Type Description
s3Path string The URL path that can be used to download the results
status string The status of the process
errorDetails string The details of any error, if there is one

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Product Bulk Upload GET Response Payload",
    "description": "The payload for a Product Bulk Upload get response",
    "type": "object",
    "required": ["s3Path", "status", "errorDetails"],
    
    "properties": {
        "s3Path": {
            "description": "The URL path that can be used to download the results",
            "type": "string"
        },
        "status": {
            "description": "The status of the process",
            "type": "string"
        },
        "errorDetails": {
            "description": "The details of any error, if there is one",
            "type": "string"
        }
    }
}

Example Response Payload:

{
    "s3Path": "https://sandbox.sellerapi.mywabi2b.com/tmp/short/productUpload/2022-7/22/17/722cbd02e5600a8a66692611d994af90cedf0dd1.json",
    "status": "Complete",
    "errorDetails": ""
}

Final Results from URL

This section describes the structure and examples of the final results that can be received from the URL given after the request is finished processing.

Response Payload Fields

Field Name Data Type Description
status string The status of the process.
gtins array The array of gtins given in the original request.

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Bulk Upload Products URL Response Payload",
    "description": "The payload for a Bulk Upload Products URL response",
    "type": "object",
    "required": ["status", "gtins"],
    
    "properties": {
        "status": {
            "description": "The status of the process.",
            "type": "string"
        },
        "gtins": {
            "description": "The array of gtins given in the original request.",
            "type": "array",
            "items": "string"
        }
    }
}
{
    "status": "Complete",
    "gtins": [
        "00025000040296"
    ]
}