{"_id":"56a98fa21801ac0d00881b88","parentDoc":null,"__v":51,"editedParams":true,"githubsync":"","version":{"_id":"567f0c06143cc60d00c1fdc1","__v":9,"project":"567f0c06143cc60d00c1fdbe","createdAt":"2015-12-26T21:52:06.734Z","releaseDate":"2015-12-26T21:52:06.734Z","categories":["567f0c07143cc60d00c1fdc2","56a9783109cb9c0d00f0c7d3","56a97837f834950d0037b363","56a9783b2d8fd90d0036eed6","56a979912d8fd90d0036eed8","5834b5691a80690f00d31faf","5834b5e4f775120f00c45f9d","5bf1a1473031e4005075ae14","5c64c200244bda003204b97f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"category":{"_id":"56a9783109cb9c0d00f0c7d3","__v":9,"pages":["56a98f8fcc0f740d005bc176","56a98fa21801ac0d00881b88","56a98fad257fbc0d00d47630","56a98fb8318e6c1700a19d02","56a99061257fbc0d00d47637","56a990712d8fd90d0036eeeb","56a992361801ac0d00881b91","56a99bfe1801ac0d00881ba1","56a9a64d09cb9c0d00f0c7f0"],"project":"567f0c06143cc60d00c1fdbe","version":"567f0c06143cc60d00c1fdc1","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-28T02:08:49.783Z","from_sync":false,"order":1,"slug":"products","title":"Products"},"editedParams2":true,"project":"567f0c06143cc60d00c1fdbe","user":"567f0baca74a1c0d003e1fba","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-28T03:48:50.694Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[{"code":"curl -X POST https://tophatter.com/merchant_api/v1/products.json \\\n-d 'access_token=YOUR_ACCESS_TOKEN' \\\n-d 'identifier=6631A' \\\n-d 'category=Electronics|Hardware (Computers/Tablets/Phones)|Mobile' \\\n-d 'title=Apple iPhone 6S' \\\n-d 'description=The Apple iPhone 6s features 3D Touch, a powerful A9 chip, and a gorgeous 4.7-inch Retina HD display. Available in Space Gray or Silver' \\\n-d 'condition=New' \\\n-d 'variations[6631A-S][identifier]=6631A-S' \\\n-d 'variations[6631A-S][color]=Silver' \\\n-d 'variations[6631A-S][quantity]=100' \\\n-d 'variations[6631A-SG][identifier]=6631A-SG' \\\n-d 'variations[6631A-SG][color]=Space Gray' \\\n-d 'variations[6631A-SG][quantity]=250' \\\n-d 'cost_basis=75' \\\n-d 'shipping_price=0' \\\n-d 'shipping_origin=China' \\\n-d 'days_to_fulfill=3' \\\n-d 'scheduling_fee_bid=1.1' \\\n-d 'primary_image=https://i.imgur.com/sXZd2Cq.jpg' \\\n-d 'extra_images=https://i.imgur.com/E0hmKxg.jpg|https://i.imgur.com/rdNujtp.jpg'","language":"curl"}]},"method":"post","results":{"codes":[{"name":"","code":"{\n  \"identifier\": \"6631A\",\n  \"internal_id\": 19301513,\n  \"category\": \"Electronics | Hardware (Computers/Tablets/Phones) | Mobile\",\n  \"title\": \"Apple iPhone 6S\",\n  \"description\": \"The Apple iPhone 6s features 3D Touch, a powerful A9 chip, and a gorgeous 4.7-inch Retina HD display. Available in Space Gray or Silver\",\n  \"condition\": \"New\",\n  \"brand\": null,\n  \"material\": null,\n  \"available_quantity\": 0,\n  \"variations\": [\n    {\n      \"identifier\": \"6631A-S\",\n      \"internal_id\": 43415169,\n      \"size\": null,\n      \"color\": \"Silver\",\n      \"quantity\": 100,\n      \"created_at\": \"2019-02-14T00:04:15-08:00\",\n      \"disabled_at\": null,\n      \"deleted_at\": null\n    },\n    {\n      \"identifier\": \"6631A-SG\",\n      \"internal_id\": 43415170,\n      \"size\": null,\n      \"color\": \"Space Gray\",\n      \"quantity\": 250,\n      \"created_at\": \"2019-02-14T00:04:15-08:00\",\n      \"disabled_at\": null,\n      \"deleted_at\": null\n    }\n  ],\n  \"retail_price\": null,\n  \"cost_basis\": 75,\n  \"minimum_bid_amount\": 1,\n  \"max_daily_schedules\": null,\n  \"scheduling_fee_bid\": 1.1,\n  \"reserve_price\": null,\n  \"shipping_price\": 0,\n  \"shipping_origin\": \"China\",\n  \"fulfillment_partner\": null,\n  \"weight\": null,\n  \"days_to_fulfill\": 3,\n  \"days_to_deliver\": 14,\n  \"expedited_shipping_price\": null,\n  \"expedited_days_to_deliver\": null,\n  \"buy_one_get_one_price\": null,\n  \"upsells\": [\n  \t{\n    \t\"type_description\": \"buy_one_get_one\",\n    \t\"amount\": \"19.0\",\n    \t\"description\": null\n    },\n    {\n       \"type_description\": \"accessory\",\n       \"amount\": \"4.0\",\n       \"description\": \"1*color box\",\n       \"identifier\": null,\n       \"image\": null\n    }\n  ],\n  \"primary_image\": \"https://i.imgur.com/sXZd2Cq.jpg\",\n  \"extra_images\": \"https://i.imgur.com/E0hmKxg.jpg|https://i.imgur.com/rdNujtp.jpg\",\n  \"all_images\": [\n    {\n      \"thumbnail\": \"https://images.tophatter.com/0c9e6cfbdfcca16eed85f84551609e8f/thumbnail.jpg\",\n      \"square\": \"https://images.tophatter.com/0c9e6cfbdfcca16eed85f84551609e8f/square.jpg\",\n      \"medium\": \"https://images.tophatter.com/0c9e6cfbdfcca16eed85f84551609e8f/medium.jpg\",\n      \"large\": \"https://images.tophatter.com/0c9e6cfbdfcca16eed85f84551609e8f/large.jpg\",\n      \"original\": \"https://images.tophatter.com/0c9e6cfbdfcca16eed85f84551609e8f/original.jpg\"\n    },\n    {\n      \"thumbnail\": \"https://images.tophatter.com/43e14d1f22720d5b9a0f463925441302/thumbnail.jpg\",\n      \"square\": \"https://images.tophatter.com/43e14d1f22720d5b9a0f463925441302/square.jpg\",\n      \"medium\": \"https://images.tophatter.com/43e14d1f22720d5b9a0f463925441302/medium.jpg\",\n      \"large\": \"https://images.tophatter.com/43e14d1f22720d5b9a0f463925441302/large.jpg\",\n      \"original\": \"https://images.tophatter.com/43e14d1f22720d5b9a0f463925441302/original.jpg\"\n    },\n    {\n      \"thumbnail\": \"https://images.tophatter.com/be8b0f664160ffe5c5e5a0bc56464771/thumbnail.jpg\",\n      \"square\": \"https://images.tophatter.com/be8b0f664160ffe5c5e5a0bc56464771/square.jpg\",\n      \"medium\": \"https://images.tophatter.com/be8b0f664160ffe5c5e5a0bc56464771/medium.jpg\",\n      \"large\": \"https://images.tophatter.com/be8b0f664160ffe5c5e5a0bc56464771/large.jpg\",\n      \"original\": \"https://images.tophatter.com/be8b0f664160ffe5c5e5a0bc56464771/original.jpg\"\n    }\n  ],\n  \"ratings_count\": 0,\n  \"ratings_average\": null,\n  \"created_at\": \"2019-02-14T00:04:15-08:00\",\n  \"updated_at\": \"2019-02-14T00:04:15-08:00\",\n  \"disabled_at\": null,\n  \"deleted_at\": null\n}","language":"json","status":200}]},"auth":"required","params":[{"_id":"56a99773257fbc0d00d47658","ref":"","in":"body","required":true,"desc":"The unique identifier or SKU that your system uses to recognize this product. Only letters, numbers, spaces, dashes and underscores are allowed. The `identifier` cannot be changed after the product has been created.","default":"","type":"string","name":"identifier"},{"_id":"56a99773257fbc0d00d4764e","ref":"","in":"body","required":true,"desc":"The category of the product. The list of valid categories can be found [here](doc:categories).","default":"","type":"string","name":"category"},{"_id":"56a99773257fbc0d00d4765a","ref":"","in":"body","required":true,"desc":"The name of the product.","default":"","type":"string","name":"title"},{"_id":"56a99773257fbc0d00d47659","ref":"","in":"body","required":true,"desc":"The description of the product. Should not contain HTML. Newlines are okay.","default":"","type":"string","name":"description"},{"_id":"56a99773257fbc0d00d4764f","ref":"","in":"body","required":false,"desc":"The condition of the product. The list of valid conditions can be found [here](doc:conditions).","default":"New","type":"string","name":"condition"},{"_id":"56a99773257fbc0d00d4764d","ref":"","in":"body","required":false,"desc":"Optional - The brand of the product (if any). The list of valid brands can be found [here](doc:brands).","default":"","type":"string","name":"brand"},{"_id":"56a99773257fbc0d00d4764b","ref":"","in":"body","required":false,"desc":"Optional - The material the product consists of. The list of recommended materials can be found [here](doc:materials).","default":"","type":"string","name":"material"},{"_id":"5769e33747693a0e00002cfb","ref":"","in":"body","required":true,"desc":"A hash of product variations, keyed by the unique identifier of each variation. A product variation consists of a unique id, size, color, and quantity. Both size and color are optional.","default":"","type":"object","name":"variations"},{"_id":"56a99773257fbc0d00d47650","ref":"","in":"body","required":true,"desc":"The lowest price (excluding shipping) at which you are willing to sell this product.","default":"","type":"int","name":"cost_basis"},{"_id":"5ce57dc5bf9b6800560cb5f2","ref":"","in":"body","required":true,"desc":"The price for this product when it appears in search results, catalogs, or your storefront.","default":"","type":"int","name":"buy_now_price"},{"_id":"56a998d23b04f20d00ecca90","ref":"","in":"body","required":false,"desc":"Optional - The Manufacturer's Suggested Retail Price. This field is recommended as it will show as a strikethrough price and appears next to the selling price for the product.","default":"","type":"int","name":"retail_price"},{"_id":"5bd92d1c39961400302cca94","ref":"","in":"body","required":false,"desc":"The starting price of a product in auction.","default":"1","type":"int","name":"minimum_bid_amount"},{"_id":"5bc043267d1cb0000384c1df","ref":"","in":"body","required":false,"desc":"The maximum scheduling fee you are willing to pay for this item to be scheduled in auction. Charged every time an item is scheduled at auction.","default":"0","type":"float","name":"scheduling_fee_bid"},{"_id":"5bd92d1c39961400302cca93","ref":"","in":"body","required":false,"desc":"The maximum number of times per day the product is scheduled. The number of schedules are also constrained by your inventory, budget, and bid.","default":"","type":"int","name":"max_daily_schedules"},{"_id":"56a99773257fbc0d00d47652","ref":"","in":"body","required":false,"desc":"The shipping price of the product when someone in the US purchases one. This price determines the shipping price to other countries when you set up your [shipping rates](https://tophatter.com/sellers/shipping_rates).","default":"0","type":"int","name":"shipping_price"},{"_id":"56a99773257fbc0d00d4764a","ref":"","in":"body","required":false,"desc":"The country the product ships from.","default":"United States","type":"string","name":"shipping_origin"},{"_id":"5c64ce95d3ee6b002a580b21","ref":"","in":"body","required":false,"desc":"The 3PL or warehouse partner you're using to fulfill orders for this product. Example: `noram`.","default":"","type":"string","name":"fulfillment_partner"},{"_id":"56a99773257fbc0d00d47647","ref":"","in":"body","required":false,"desc":"The weight (in ounces) of the package when you ship this item. Used to help determine shipping costs in certain scenarios.","default":"","type":"int","name":"weight"},{"_id":"56a99773257fbc0d00d47649","ref":"","in":"body","required":false,"desc":"The number of days (after purchase) that it will take you to process & fulfill the order by shipping the item.","default":"3","type":"int","name":"days_to_fulfill"},{"_id":"5772e233dceb570e003a91cb","ref":"","in":"body","required":false,"desc":"Optional - The shipping price of the product when someone in the US purchases one and chooses expedited shipping.","default":"","type":"int","name":"expedited_shipping_price"},{"_id":"5772e233dceb570e003a91ca","ref":"","in":"body","required":false,"desc":"Optional - The number of days you expect the shipment to be in transit to the buyer when the buyer chooses expedited shipping.","default":"","type":"int","name":"expedited_days_to_deliver"},{"_id":"5834b49e10b9b40f006a7c88","ref":"","in":"body","required":false,"desc":"Optional - Offer \"Buy One Get One\" for $XX (should include any additional shipping cost).","default":"","type":"int","name":"buy_one_get_one_price"},{"_id":"56a99773257fbc0d00d47646","ref":"","in":"body","required":true,"desc":"URL of a photo of your product. Link directly to the image, not the page where it is located. We accept JPEG, PNG or GIF format. Images should be at least 500x480 pixels in size.","default":"","type":"string","name":"primary_image"},{"_id":"56a99773257fbc0d00d47645","ref":"","in":"body","required":true,"desc":"URLs of extra photos of your product. Link directly to the image, not the page where it is located. Same rules apply as primary_image. At least one extra image is required. You can specify multiple URLs separated by the character \"|\". Example: http://imgur.com/foo|http://imgur.com/bar","default":"","type":"string","name":"extra_images"}],"url":"/products.json"},"isReference":false,"order":4,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Common Issue - Variation Consistency\",\n  \"body\": \"Each product must have one or more variations. Additionally, all variations should be consistent with respect to sizes and colors. In particular, all variations for a given product must have just a size, just a color, or both a size and color.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Error Handling\",\n  \"body\": \"If a `200` response is returned then the product has been successfully created. You can read more about error handling [here](doc:errors).\"\n}\n[/block]","excerpt":"","slug":"product-create","type":"endpoint","title":"Create a Product"}

postCreate a Product


Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

identifier:
required
string
The unique identifier or SKU that your system uses to recognize this product. Only letters, numbers, spaces, dashes and underscores are allowed. The `identifier` cannot be changed after the product has been created.
category:
required
string
The category of the product. The list of valid categories can be found [here](doc:categories).
title:
required
string
The name of the product.
description:
required
string
The description of the product. Should not contain HTML. Newlines are okay.
condition:
stringNew
The condition of the product. The list of valid conditions can be found [here](doc:conditions).
brand:
string
Optional - The brand of the product (if any). The list of valid brands can be found [here](doc:brands).
material:
string
Optional - The material the product consists of. The list of recommended materials can be found [here](doc:materials).
variations:
required
object
A hash of product variations, keyed by the unique identifier of each variation. A product variation consists of a unique id, size, color, and quantity. Both size and color are optional.
cost_basis:
required
integer
The lowest price (excluding shipping) at which you are willing to sell this product.
buy_now_price:
required
integer
The price for this product when it appears in search results, catalogs, or your storefront.
retail_price:
integer
Optional - The Manufacturer's Suggested Retail Price. This field is recommended as it will show as a strikethrough price and appears next to the selling price for the product.
minimum_bid_amount:
integer1
The starting price of a product in auction.
scheduling_fee_bid:
float0
The maximum scheduling fee you are willing to pay for this item to be scheduled in auction. Charged every time an item is scheduled at auction.
max_daily_schedules:
integer
The maximum number of times per day the product is scheduled. The number of schedules are also constrained by your inventory, budget, and bid.
shipping_price:
integer0
The shipping price of the product when someone in the US purchases one. This price determines the shipping price to other countries when you set up your [shipping rates](https://tophatter.com/sellers/shipping_rates).
shipping_origin:
stringUnited States
The country the product ships from.
fulfillment_partner:
string
The 3PL or warehouse partner you're using to fulfill orders for this product. Example: `noram`.
weight:
integer
The weight (in ounces) of the package when you ship this item. Used to help determine shipping costs in certain scenarios.
days_to_fulfill:
integer3
The number of days (after purchase) that it will take you to process & fulfill the order by shipping the item.
expedited_shipping_price:
integer
Optional - The shipping price of the product when someone in the US purchases one and chooses expedited shipping.
expedited_days_to_deliver:
integer
Optional - The number of days you expect the shipment to be in transit to the buyer when the buyer chooses expedited shipping.
buy_one_get_one_price:
integer
Optional - Offer "Buy One Get One" for $XX (should include any additional shipping cost).
primary_image:
required
string
URL of a photo of your product. Link directly to the image, not the page where it is located. We accept JPEG, PNG or GIF format. Images should be at least 500x480 pixels in size.
extra_images:
required
string
URLs of extra photos of your product. Link directly to the image, not the page where it is located. Same rules apply as primary_image. At least one extra image is required. You can specify multiple URLs separated by the character "|". Example: http://imgur.com/foo|http://imgur.com/bar

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "title": "Common Issue - Variation Consistency", "body": "Each product must have one or more variations. Additionally, all variations should be consistent with respect to sizes and colors. In particular, all variations for a given product must have just a size, just a color, or both a size and color." } [/block] [block:callout] { "type": "info", "title": "Error Handling", "body": "If a `200` response is returned then the product has been successfully created. You can read more about error handling [here](doc:errors)." } [/block]