/Items POST

Allows you to list an item for sale.

URL

/Items

Verb

Post

Headers

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 single 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

Characteristics: {
  NumberOfRoundsPerQuantityOne: 1000
}

PaymentMethods: {
                    Check: true,
                    VisaMastercard: true,
                    COD: false,
                    Escrow: false,
                    Amex: false,
                    PayPal: false,
                    Discover: false,
                    SeeItemDesc: true,
                    CertifiedCheck: true,
                    USPSMoneyOrder: true,
                    MoneyOrder: false,
                    FreedomCoin: false,
                    Financing: true
                }

PremiumFeatures: {
                HasViewCounter: true,
                IsFeaturedItem: true,
                IsHighlighted: true,
                IsShowCaseItem: true,
                IsTitleBoldface: true,
                IsSponsoredOnsite: 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""
                }

    ShippingClassCosts: {
    Overnight: 10.00,
    TwoDay: 9.00,
    ThreeDay: 8.00,
    Ground: 7.00,
    FirstClass: 6.00,
    Priority: 5.00,
    InStorePickup: 4.00,
    AlaskaHawaii: 3.00,
    Other: 2.00
    }

    ShippingClassesSupported: {
    Overnight: true,
    TwoDay: true,
    ThreeDay: true,
    Ground: true,
    FirstClass: true,
    Priority: true,
    InStorePickup: true,
    AlaskaHawaii: true,
    Other: true
    }

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