/Items POST

Allows you to list an item for sale.

URL
/Items
Verb
Post

Headers

Header Data Type Valid Values Required Description
Content-Type string application/json YES The format your data will be sent to our site.
X-DevKey string string YES The devkey assigned to the developer.
X-AccessToken string string YES The token acquired from a POST to Users/AccessToken.

Input

NOTE: Variables to place in the body of the request.

This API call is different than most of the other API calls in our system. Most requests in our API are sinlge part requests where the Content-Type header describes the single type of content in the body of the request (ie. text/json). This request however is a multipart request which allows you to list an item for sale and upload pictures of the item at the same time in the same HTTP requst. The Content-Type header of this request must be set to multipart/form-data.

The individual parts of this request must contain a single part with the data describing the item listed. Additional optional parts of the request can contain a thumbnail and pictures. For the data part, the Content-Disposition must be set to form-data; name="data". If a thumbnail is desired, that part must have a Content-Disposition of form-data; name="thumbnail"; filename="yourfilename.jpg . If pictures are included in the request, each picture part must have a Content-Disposition of form-data; name="picture"; filename="yourfilename.jpg".

An example request from Fiddler:

POST https://api.gunbroker.com/items HTTP/1.1
User-Agent: curl/7.35.0
Host: rest
Accept: */*
X-DevKey: XXX
X-AccessToken: XXX
Content-Length: 130625
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryR7f7XrG1vJhOfHzu
------WebKitFormBoundaryR7f7XrG1vJhOfHzu
Content-Disposition: form-data; name="data"
{
    CategoryID: 3026,
    Title: "Test Title",
    Description: "Test description",
    [...other JSON data not shown...]
}
------WebKitFormBoundaryR7f7XrG1vJhOfHzu
Content-Disposition: form-data; name="thumbnail"; filename="gun1.jpg"
Content-Type: image/jpg
[binary file contents not shown]
------WebKitFormBoundaryR7f7XrG1vJhOfHzu
Content-Disposition: form-data; name="picture"; filename="gun2.jpg"
Content-Type: image/jpg
[binary file contents not shown]
------WebKitFormBoundaryR7f7XrG1vJhOfHzu
Content-Disposition: form-data; name="picture"; filename="gun3.gif"
Content-Type: image/gif
[binary file contents not shown]
------WebKitFormBoundaryR7f7XrG1vJhOfHzu--

A CURL command line example (must be on one line):


curl
    -H "Content-Type: multipart/form-data"
    -H "X-DevKey: XXX"
    -H "X-AccessToken: XXX"
    -F "thumbnail=@C:\temp\gunthumb.gif;filename=gunthumb.gif"
    -F "data=@C:\temp\ItemListing.json; type=application/json"
    -F "picture=@C:\temp\gunpic1.jpg;filename=gunpic1.jpg"
    -F "picture=@C:\temp\gunpic2.jpg;filename=gunpic2.jpg"
    -X POST https://api.gunbroker.com//items -i -v

Parameter Data Type Valid Values Description
AutoAcceptPrice decimal positive # The minimum price for an offer to be automatically accepted.
AutoRejectPrice decimal positive # The maximum price for an offer to be automatically rejected
AutoRelist integer 1 - Do Not Relist

2 - Relist Until Sold

3 - Relist Fixed Count
How the item should be relisted.
AutoRelistFixedCount integer positive # The number of times the item should relist when AutoRelist=3.
BuyNowPrice decimal positive # Optional. The price you will sell the item for immediately. If used, the price must be greater than or equal to the Starting Bid and Reserve Price.
CanOffer boolean true/false Specifies whether the item is enabled for offer functionality. If true, you must also send AutoAcceptPrice and AutoRejectPrice.
CategoryID integer positive # The single best category id for your item.
Condition integer 1 - Factory New

2 - New Old Stock

3 - Used
The condition of the item.
CountryCode string 2 character The ISO 2 character country code where the item is located. For example: Country:"US" for United States
Description string string The description of the item. If the description contains links or image references, they must all be secure (https://).
FixedPrice decimal positive # Optional. The price of each item when selling fixed price items.
InspectionPeriod integer 1 - AS IS - No refund or exchange

2 - No refund but item can be returned for exchange or store credit within fourteen days

3 - No refund but item can be returned for exchange or store credit within thirty days

4 - Three Days from the date the item is received

5 - Three Days from the date the item is received, including the cost of shipping

6 - Five Days from the date the item is received

7 - Five Days from the date the item is received, including the cost of shipping

8 - Seven Days from the date the item is received

9 - Seven Days from the date the item is received, including the cost of shipping

10 - Fourteen Days from the date the item is received

11 - Fourteen Days from the date the item is received, including the cost of shipping

12 - 30 day money back guarantee

13 - 30 day money back guarantee including the cost of shipping

14 - Factory Warranty
Optional. The return policy / inspection period for this listing
IsFFLRequired boolean true/false Whether the item may only be shipped to a licensed Federal Firearms License (FFL) holder.
ListingDuration integer 1 - One day.

3 - Three days.

5 - Five days.

7 - Seven days.

9 - Nine days.

10 - Ten days.

11 - Eleven days.

12 - Twelve days.

13 - Thirteen days.

14 - Fourteen days.

30 - Thirty days. (Fixed price items only)

60 - Sixty days. (Fixed price items only)

90 - Ninety days. (Fixed price items only)
How long before the listing ends.
MfgPartNumber string string The manufacturing part number.
PaymentMethods object SeeItemDesc - true/false

Check - true/false

VisaMastercard - true/false

COD - true/false

Escrow - true/false

Amex - true/false

Discover - true/false

PayPal - true/false

CertifiedCheck - true/false

USPSMoneyOrder - true/false

MoneyOrder - true/false

The payment methods you will accept. Each object property is a boolean. For example:
PaymentMethods: {
                    Check: true,
                    VisaMastercard: true,
                    COD: false,
                    Escrow: false,
                    Amex: false,
                    PayPal: false,
                    Discover: false,
                    SeeItemDesc: true,
                    CertifiedCheck: true,
                    USPSMoneyOrder: true,
                    MoneyOrder: false
                }
PictureURLs string Array of picture URLs Optional. All picture URLs must be secure. For example: PictureURLs:["https://host/1.jpg","https://host/2.jpg"]
PremiumFeatures object object Optional. The premium features you want for the item listing. Please note there are additional charges for these features. For example:
PremiumFeatures: {
                HasViewCounter: true,
                IsFeaturedItem: true,
                IsHighlighted: true,
                IsShowCaseItem: true,
                IsTitleBoldface: true,
                ScheduledStartingDate: "2015-11-21T18:20:07Z",
                SubTitle: "Your SubTitle Text",
                ThumbnailURL: "http://host/yourfile.jpg",
                TitleColor: "Red" // TitleColor must be: "Red", "Green", or "Blue""
                }
NOTE: ScheduledStartingDate must be set in US Eastern Time ( GMT-5 ) Offical GunBroker Time
PostalCode string string The postal code where the item is located.
Quantity integer positive # The quantity of items for sale. Must be 1 for auctions. Fixed price listings can have any quantity.
ReservePrice decimal positive # Optional. The price the bidding must reach before you will sell the item.
SalesTaxes object Array of SalesTax objects Optional. If you must collect sales tax, the states and tax rates you collect. For example: SalesTaxes: [{ State: "GA", TaxRate: 5.25 }, { State: "CA", TaxRate: 10.625 }]
UseDefaultSalesTax boolean true/false Optional. If your listing preferences indicate whether you collect or do not collect sales tax and this value is set to true, any values passed in for SalesTaxes will be ignored and the values for SalesTaxes in your listing preferences will be used including seller not collecting sales tax. If your listing preferences indicate you must specify whether you collect or do not collect sales tax, then the SalesTaxes values passed will be used if present, otherwise the item will be listed as not requiring sales tax.
SerialNumber string string Optional. The serial number of the item.
ShippingClassCosts object object Optional. The shipping costs for each supported shipping class. For example:
ShippingClassCosts: {
    Overnight: 10.00,
    TwoDay: 9.00,
    ThreeDay: 8.00,
    Ground: 7.00,
    FirstClass: 6.00,
    Priority: 5.00,
    Other: 4.00
}
ShippingClassesSupported object Overnight - true/false

TwoDay - true/false

ThreeDay - true/false

Ground - true/false

FirstClass - true/false

Priority - true/false

Other - true/false
Required if not using a shipping profile. The shipping classes you support. Each object property is a boolean. For example:
ShippingClassesSupported: {
    Overnight: true,
    TwoDay: true,
    ThreeDay: true,
    Ground: true,
    FirstClass: true,
    Priority: true,
    Other: true
}
ShippingProfileID integer positive # Optional. The shipping profile id to use to configure the available shipping options and costs for this item. If using a shipping profile, WhoPaysForShipping must be set to 16.
SKU string string Optional. The SKU of the item.
StandardTextID int int The ID of the Standard Text for Additional Terms of Sale version linked to the item for StandardTextVersionID
StartingBid decimal positive # Optional. The starting bid is the the least amount that a user will be able to bid on the item.
Title string string The item title. 50 characters maximum, NO HTML, no asterisks, no quotes, NO ALL CAPS. Invalid characters will be stripped from the value entered.
UPC string string Optional. The UPC code of the item.
Weight decimal positive # Optional. The weight of the item.
WeightUnit integer 1 - Pounds

2 - Kilograms
Optional. The unit of weight for the item.
WhoPaysForShipping integer 1 - See item description

2 - Seller pays for shipping

4 - Buyer pays actual shipping cost

8 - Buyer pays fixed amount

16 - Use shipping profile
Specifies who pays for shipping on the item. Use the values 2, 4, or 8. If the user should see the item description then add 1 to the value. For example, if the seller pays for shipping and the user should see the item description, the value to use would be 3.
WillShipInternational boolean true/false Whether you will ship the item internationally.

Output

If the search parameters are not valid, you will receive a 400 BadRequest and a Message Response indicating the reason.

If there are no errors with the input parameters, this call will respond with a 200 OK and a Message Response indicating the newly listed item number.

Links

Rel Description Condition
self The item details