### URL Versioning Example: Get Items

Source: https://api.gunbroker.com/Help

This example shows how to construct a URL to access the GunBroker.com REST API, specifically for retrieving a list of items matching a keyword. It utilizes the 'v1' version segment of the API.

```HTTP
https://api.gunbroker.com/v1/Items?Keywords=ruger
```

--------------------------------

### Example PremiumFeatures Object

Source: https://api.gunbroker.com/User/Help/ItemsPost

Illustrates the optional premium features that can be enabled for a listing, such as featured status, highlighting, and scheduled start times. Note that 'ThumbnailURL' is no longer supported and 'ScheduledStartingDate' requires US Eastern Time.

```json
{
    "HasViewCounter": true,
    "IsFeaturedItem": true,
    "IsHighlighted": true,
    "IsShowCaseItem": true,
    "IsTitleBoldface": true,
    "IsSponsoredOnsite": true,
    "ScheduledStartingDate": "2015-11-21T18:20:07Z",
    "SubTitle": "Your SubTitle Text",
    "ThumbnailURL": "_No longer supported_",
    "TitleColor": "Red"
}
```

--------------------------------

### Get Seller Information (Example)

Source: https://api.gunbroker.com/User/Help/SellerGet_devkey=darkkermit

This example demonstrates how to make a GET request to the /Seller endpoint to retrieve seller information. It includes common headers required for authentication and specifies the expected JSON output format.

```http
GET /Seller HTTP/1.1
Host: api.gunbroker.com
Content-Type: application/json
X-DevKey: YOUR_DEV_KEY
X-AccessToken: YOUR_ACCESS_TOKEN

{
    "UserID": "SELLER_USER_ID"
}
```

--------------------------------

### Example ShippingClassesSupported Object

Source: https://api.gunbroker.com/User/Help/ItemsPost_devkey=darkkermit

An example of the ShippingClassesSupported object, which specifies which shipping classes are supported for an item. This is required if a shipping profile is not used. Each property is a boolean.

```json
{
    "Overnight": true,
    "TwoDay": true,
    "ThreeDay": true,
    "Ground": true,
    "FirstClass": true,
    "Priority": true,
    "InStorePickup": true,
    "AlaskaHawaii": true,
    "Other": true
}
```

--------------------------------

### Example SalesTaxes Array

Source: https://api.gunbroker.com/User/Help/ItemsPost_devkey=darkkermit

An example of the SalesTaxes array, which specifies the states and tax rates for collecting sales tax. This is optional and ignored if TaxCloud is used.

```json
[
  { "State": "GA", "TaxRate": 5.25 },
  { "State": "CA", "TaxRate": 10.625 }
]
```

--------------------------------

### Pictures Array Example

Source: https://api.gunbroker.com/User/Help/ListingPost_devkey=darkkermit

An example of the Pictures array structure for API requests. This array contains objects, each representing an image to be uploaded for the listing, specifying the URL and whether it's hosted externally or uploaded via Aurigma.

```json
[
    {
        "url": "https://example.com/image.jpg",
        "is_aurigma": false
    }
]
```

--------------------------------

### GET /Items

Source: https://api.gunbroker.com/User/Help/Urls

This endpoint searches live items. AccessToken is optional.

```APIDOC
## GET /Items

### Description
Search live items

### Method
GET

### Endpoint
/Items

### Parameters
#### Query Parameters
- **keyword** (string) - Optional - Search keyword.
- **categoryID** (integer) - Optional - Category ID.

### Request Example
None

### Response
#### Success Response (200)
- ItemsData (array) - Array of item objects.

#### Response Example
[
  {
    "itemID": 123,
    "name": "Example Item",
    "price": 100.00
  }
]

```

--------------------------------

### Multipart Request Example (cURL)

Source: https://api.gunbroker.com/User/Help/ItemsPost

This example shows how to construct a multipart/form-data POST request using the cURL command-line tool to list an item and upload associated pictures to the Gunbroker API. It highlights the use of -F flags for different form data parts, including specifying content types and filenames.

```bash
curl \
    -H "Content-Type: multipart/form-data" \
    -H "X-DevKey: XXX" \
    -H "X-AccessToken: XXX" \
    -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
```

--------------------------------

### Example PaymentMethods Configuration in JSON

Source: https://api.gunbroker.com/User/Help/ListingPut_devkey=darkkermit

This JSON snippet demonstrates how to configure the `PaymentMethods` object for the GunBroker API. It includes various payment options, each set to a boolean value indicating acceptance.

```json
{
    "Amex": true,
    "CertifiedCheck": true,
    "Check": true,
    "COD": true,
    "Discover": true,
    "Escrow": true,
    "FreedomCoin": true,
    "MoneyOrder": true,
    "PayPal": true,
    "USPSMoneyOrder": true,
    "VisaMastercard": true
}
```

--------------------------------

### POST /websites/api_gunbroker/listings

Source: https://api.gunbroker.com/User/Help/ListingRelistGet_devkey=darkkermit

Create a new item listing with detailed specifications.

```APIDOC
## POST /websites/api_gunbroker/listings

### Description
This endpoint allows you to create a new item listing on the website with comprehensive details about the item, its pricing, condition, and selling options.

### Method
POST

### Endpoint
/websites/api_gunbroker/listings

### Parameters
#### Request Body
- **AllowLayaway** (boolean) - Optional - Whether or not this ListingItem allows for layaway.
- **AuctionID** (integer) - Optional - The AuctionID associated with the Item indicating its creation source.
- **AutoAcceptPrice** (decimal) - Optional - The minimum price for an offer to be automatically accepted. Requires `CanOffer` to be true.
- **AutoRejectPrice** (decimal) - Optional - The maximum price for an offer to be automatically rejected. Requires `CanOffer` to be true.
- **AutoRelist** (integer) - Optional - How the item should be relisted. For an auction, this is the number of auto relists up to 999. Use 32000 for an auction to relist until sold, or 35000 for a fixed price listing to relist until quantity runs out. Do not specify if no auto relist is required.
- **BuyNowPrice** (decimal) - 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) - Optional - Specifies whether the item is enabled for offer functionality. If true, you must also send AutoAcceptPrice and AutoRejectPrice.
- **Category** (integer) - Required - The single best category id for your item.
- **Characteristics** (Array of Characteristics) - Optional - An Array of values selected as this item's characteristics.
- **Condition** (integer) - Required - The condition of the item. Valid values: 1 (Factory New), 2 (New Old Stock), 3 (Used).
- **CountryCode** (string) - Required - The ISO 2 character country code where the item is located. For example: `"US"`.
- **Description** (string) - Required - The description of the item. If the description contains links or image references, they must all be secure (https://).
- **ExcludeStates** (string) - Optional - Comma separated list of two digit States where the seller has indicated they will not ship.
- **FFLRequired** (boolean) - Optional - Whether the item may only be shipped to a licensed Federal Firearms License (FFL) holder.
- **FixedPrice** (decimal) - Optional - The price of each item when selling fixed price items.
- **HasCharacteristics** (boolean) - Optional - Whether the item has characteristics associated with it.
- **GTIN** (string) - Optional - The Global Trade Item Number (GTIN) of the item. If the GTIN is also a valid UPC and UPC is not specified, this will also update the UPC of the item.
- **InspectionPeriod** (integer) - Required - The return policy / inspection period for this listing. Valid values are documented in the API reference.
- **ListingDuration** (integer) - Required - How long before the listing ends. Valid values: 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 30, 60, 90. Note: 1 and 3 day listings do not allow a Reserve Price.
- **MPN** (string) - Optional - The manufacturing part number.
- **PaymentMethods** (object) - Required - The payment methods you will accept. Each object property is a boolean (e.g., `{"Amex": true, "PayPal": false}`).
- **Pictures** (Array of strings) - Optional - An array of secure picture URLs to upload for the item.

### Request Example
```json
{
  "AllowLayaway": true,
  "AutoAcceptPrice": 150.00,
  "BuyNowPrice": 200.00,
  "CanOffer": true,
  "Category": 12345,
  "Condition": 1,
  "CountryCode": "US",
  "Description": "A brand new, factory sealed item.",
  "FixedPrice": 190.00,
  "ListingDuration": 7,
  "PaymentMethods": {
    "Amex": true,
    "PayPal": true,
    "VisaMastercard": true
  },
  "Pictures": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.png"
  ]
}
```

### Response
#### Success Response (200)
- **ListingID** (integer) - The unique identifier for the newly created listing.
- **Status** (string) - The status of the listing creation (e.g., "Success", "Pending").

#### Response Example
```json
{
  "ListingID": 987654321,
  "Status": "Success"
}
```
```

--------------------------------

### GET /BillingInformation

Source: https://api.gunbroker.com/User/Help/Urls

This endpoint allows you to get billing information. AccessToken is required.

```APIDOC
## GET /BillingInformation

### Description
Get billing information.

### Method
GET

### Endpoint
/BillingInformation

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- BillingInformationData (object) - Billing information details.

#### Response Example
{
  "name": "John Doe",
  "address": "123 Main St",
  "creditCard": "************1234"
}

```

--------------------------------

### GET /ItemsSelling

Source: https://api.gunbroker.com/User/Help/Urls_devkey=darkkermit

This endpoint gets the user's active listings. Access to this endpoint requires an access token.

```APIDOC
## GET /ItemsSelling

### Description
Gets the user's active listings.

### Method
GET

### Endpoint
/ItemsSelling

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- List of active items for sale

#### Response Example
{
  "itemID": 123,
  "name": "Rifle",
  "currentPrice": 900.0
```

--------------------------------

### Example Supported Shipping Classes Configuration

Source: https://api.gunbroker.com/User/Help/ItemsPost

Illustrates how to specify which shipping classes are supported for an item. This is required if a shipping profile is not being used.

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

--------------------------------

### GET /ItemsScheduled

Source: https://api.gunbroker.com/User/Help/Urls_devkey=darkkermit

This endpoint gets your scheduled items. Access to this endpoint is optional and may require an access token.

```APIDOC
## GET /ItemsScheduled

### Description
Get your scheduled items.

### Method
GET

### Endpoint
/ItemsScheduled

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- List of scheduled items

#### Response Example
{
  "itemID": 123,
  "name": "Rifle",
  "scheduledTime": "2024-01-02T10:00:00Z"
}

```

--------------------------------

### Create Item Listing API

Source: https://api.gunbroker.com/User/Help/ListingRelistEditPost_devkey=darkkermit

This section details the parameters required for creating a new item listing through the API. It covers various aspects of the listing, from pricing and condition to payment methods and images.

```APIDOC
## POST /websites/api_gunbroker/listings

### Description
API endpoint for creating a new item listing on Gunbroker.

### Method
POST

### Endpoint
/websites/api_gunbroker/listings

### Parameters
#### Request Body
- **AutoAcceptPrice** (decimal) - Optional - The minimum price for an offer to be automatically accepted.
- **AutoRejectPrice** (decimal) - Optional - The maximum price for an offer to be automatically rejected.
- **AutoRelist** (integer) - Optional - Specifies how the item should be relisted. Use 32000 for auctions to relist until sold, 35000 for fixed price listings to relist until quantity runs out. Do not specify if no auto relist is required.
- **BuyNowPrice** (decimal) - Optional - The price at which the item can be bought immediately. Must be greater than or equal to the Starting Bid and Reserve Price.
- **CanOffer** (boolean) - Optional - Specifies whether the item is enabled for offer functionality. If true, AutoAcceptPrice and AutoRejectPrice must also be sent.
- **Category** (integer) - Required - The single best category ID for your item.
- **Characteristics** (Array of Characteristics) - Optional - An array of values selected as this item's characteristics.
- **Condition** (integer) - Required - The condition of the item (1: Factory New, 2: New Old Stock, 3: Used).
- **CountryCode** (string) - Required - The ISO 2 character country code where the item is located (e.g., "US").
- **Description** (string) - Required - The description of the item. All links and image references must be secure (https://).
- **ExcludeStates** (string) - Optional - A comma-separated list of two-digit states where the seller will not ship.
- **FFLRequired** (boolean) - Optional - Whether the item may only be shipped to a licensed Federal Firearms License (FFL) holder.
- **Financing** (boolean) - Optional - Specifies if the account is enabled to sell with financing.
- **GTIN** (string) - Optional - The Global Trade Item Number (GTIN) of the item.
- **InspectionPeriod** (integer) - Optional - The return policy / inspection period for this listing (e.g., 12 for 30 day money back guarantee).
- **ListingDuration** (integer) - Required - How long before the listing ends (e.g., 7 for seven days, 30 for thirty days for fixed price items).
- **MPN** (string) - Optional - The manufacturing part number.
- **PaymentMethods** (object) - Optional - An object specifying accepted payment methods (e.g., {"Amex": true, "PayPal": false}). Ignored if User account is configured for OutdoorPay / OmniPay.
- **Pictures** (string) - Optional - An array of picture URLs to upload. All picture URLs must be secure.

### Request Example
```json
{
  "AutoAcceptPrice": 100.00,
  "AutoRejectPrice": 50.00,
  "AutoRelist": 32000,
  "BuyNowPrice": 150.00,
  "CanOffer": true,
  "Category": 12345,
  "Condition": 1,
  "CountryCode": "US",
  "Description": "This is a great item for sale.",
  "ExcludeStates": "CA,TX",
  "FFLRequired": false,
  "Financing": true,
  "GTIN": "123456789012",
  "InspectionPeriod": 12,
  "ListingDuration": 7,
  "MPN": "MPN12345",
  "PaymentMethods": {
    "Amex": true,
    "PayPal": true,
    "VisaMastercard": true
  },
  "Pictures": [
    {
      "URL": "https://example.com/image1.jpg",
      "IsAurigma": false
    }
  ]
}
```

### Response
#### Success Response (200)
- **listingId** (string) - The unique identifier for the newly created listing.

#### Response Example
```json
{
  "listingId": "abcdef1234567890"
}
```
```

--------------------------------

### Example ShippingClassCosts Object

Source: https://api.gunbroker.com/User/Help/ItemsPost_devkey=darkkermit

An example of the ShippingClassCosts object, which defines the shipping costs for various supported shipping classes. This is an optional parameter.

```json
{
    "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
}
```

--------------------------------

### Example Payment Methods Object (JSON)

Source: https://api.gunbroker.com/User/Help/ListingEditGet_devkey=darkkermit

Demonstrates the structure for specifying accepted payment methods in a JSON object. Each payment method is a boolean indicating whether it is accepted.

```json
{
    "Amex": true,
    "CertifiedCheck": true,
    "Check": true,
    "COD": true,
    "Discover": true,
    "Escrow": true,
    "Financing": true,
    "FreedomCoin": true,
    "MoneyOrder": true,
    "PayPal": true,
    "USPSMoneyOrder": true,
    "VisaMastercard": true
}
```

--------------------------------

### GET /Items?{itemIDs}

Source: https://api.gunbroker.com/User/Help/Urls_devkey=darkkermit

This endpoint allows you to get multiple items by ID. Access to this endpoint is optional and may require an access token.

```APIDOC
## GET /Items?{itemIDs}

### Description
Get multiple items by ID.

### Method
GET

### Endpoint
/Items?{itemIDs}

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- List of items

#### Response Example
{
  "itemID": 123,
  "name": "Rifle",
  "price": 1000.00
}

```

--------------------------------

### Search Marketplace Listings - Bash Example

Source: https://context7.com/context7/api_gunbroker/llms.txt

Shows how to search for marketplace items using various filters such as keywords, category, price, shipping options, and sorting preferences. Requires a DevKey. The response provides a paginated list of matching items with details like title, current bid, and seller information.

```bash
# Search for Ruger pistols under $800 with free shipping
curl -X GET "https://api.gunbroker.com/v1/Items?Keywords=ruger%20pistol&CategoryID=3026&MaxPrice=800&ShippingType=0&PageIndex=1&PageSize=25&SortBy=3" \
  -H "X-DevKey: 12345678-1234-1234-1234-123456789abc"

# Response (200 OK):
{
  "Count": 342,
  "PageIndex": 1,
  "PageSize": 25,
  "Results": [
    {
      "ItemID": 912345678,
      "Title": "Ruger LCP II 380 ACP 2.75\" Pistol - New In Box",
      "CategoryID": 3026,
      "CategoryName": "Semi Auto Pistols - Small Frame",
      "CurrentBid": 285.00,
      "BuyNowPrice": 325.00,
      "HasBuyNow": true,
      "Bids": 3,
      "EndingDate": "2025-10-18T19:45:00Z",
      "IsFFLRequired": true,
      "Condition": {"Key": 1, "Value": "Factory New"},
      "Seller": {
        "UserID": 12345,
        "Username": "TopGunDealer",
        "FeedbackRating": "A+(2450)",
        "IsTop25Seller": true,
        "IsVerified": true
      },
      "Pictures": [
        "https://image.gunbroker.com/912345678/1234567890/thumb.jpg"
      ],
      "Location": "Phoenix, AZ"
    }
  ],
  "Links": [
    {
      "Rel": "next",
      "Href": "https://api.gunbroker.com/v1/Items?Keywords=ruger%20pistol&PageIndex=2&PageSize=25",
      "Verb": "GET"
    }
  ]
}
```

--------------------------------

### POST /Listing

Source: https://api.gunbroker.com/User/Help/ListingPost_devkey=darkkermit

Allows you to list an item for sale, including characteristics. Requires authentication via developer key and access token.

```APIDOC
## POST /Listing

### Description
Allows you to list an item for sale, including its characteristics.

### Method
POST

### Endpoint
/Listing

### Headers
- **Content-Type** (string) - Required - The format your data will be sent to our site. Valid values: application/json.
- **X-DevKey** (string) - Required - The devkey assigned to the developer.
- **X-AccessToken** (string) - Required - The token acquired from a POST to Users/AccessToken.

### Request Body
(Details for request body not provided in the input text)

### Request Example
(No example provided in the input text)

### Response
#### Success Response (200)
(Details for success response not provided in the input text)

#### Response Example
(No example provided in the input text)
```

--------------------------------

### Get Category Hierarchy - GET /Categories/Hierarchy

Source: https://context7.com/context7/api_gunbroker/llms.txt

Retrieves the complete hierarchical tree of product categories. Each category includes its ID, name, and FFL requirement, with nested children for subcategories.

```bash
curl -X GET https://api.gunbroker.com/v1/Categories/Hierarchy \
  -H "X-DevKey: 12345678-1234-1234-1234-123456789abc"
```

--------------------------------

### Example Shipping Costs Configuration

Source: https://api.gunbroker.com/User/Help/ItemsPost

Shows how to define shipping costs for various shipping classes. This is an optional field used to specify per-class shipping rates.

```json
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
}
```

--------------------------------

### Get All Saved Searches - GET /SavedSearches

Source: https://context7.com/context7/api_gunbroker/llms.txt

Retrieves a list of all saved searches associated with the authenticated user. Includes details like search name, criteria, and notification status.

```bash
curl -X GET https://api.gunbroker.com/v1/SavedSearches \
  -H "X-DevKey: 12345678-1234-1234-1234-123456789abc" \
  -H "X-AccessToken: abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx"
```

--------------------------------

### Example JSON for Premium Features

Source: https://api.gunbroker.com/User/Help/ListingEditGet_devkey=darkkermit

Illustrates the structure for the 'PremiumFeatures' object, detailing various options available for enhancing item listings. These features may incur additional charges. Note that 'ScheduledStartingDate' must be in US Eastern Time (GMT-5).

```json
{
"PremiumFeatures": {
    "HasViewCounter": true,
    "IsFeaturedItem": true,
    "IsHighlighted": true,
    "IsShowCaseItem": true,
    "IsTitleBoldface": true,
    "IsSponsoredOffsite": true,
    "IsSponsoredOnsite": true,
    "ScheduledStartingDate": "2020-03-21T18:20:07Z",
    "Subtitle": "Your Subtitle Text",
    "TitleColor": "Red" 
}
}
```

--------------------------------

### Get User Feedback Summary - GET /Feedback/Summary/{UserID}

Source: https://context7.com/context7/api_gunbroker/llms.txt

Retrieves a summary of a user's feedback, including total counts, ratings, and recent activity. Requires the UserID.

```bash
curl -X GET https://api.gunbroker.com/v1/Feedback/Summary/12345 \
  -H "X-DevKey: 12345678-1234-1234-1234-123456789abc"
```

--------------------------------

### GET /Items/Showcase

Source: https://api.gunbroker.com/User/Help/Urls_devkey=darkkermit

This endpoint provides random showcase items. Access to this endpoint requires an access token.

```APIDOC
## GET /Items/Showcase

### Description
Random showcase items.

### Method
GET

### Endpoint
/Items/Showcase

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- List of showcase items

#### Response Example
{
  "itemID": 123,
  "name": "Rifle",
  "price": 1000.00
}

```

--------------------------------

### Characteristics Object Example (JSON)

Source: https://api.gunbroker.com/User/Help/ItemsPost_devkey=darkkermit

This snippet shows an example of the 'Characteristics' object within the item listing data. It specifically demonstrates how to set the 'NumberOfRoundsPerQuantityOne' property, which is used for ammunition-related items to determine per-round costs.

```json
Characteristics: {
  NumberOfRoundsPerQuantityOne: 1000
}
```

--------------------------------

### Example PaymentMethods Object

Source: https://api.gunbroker.com/User/Help/ItemsPost

Demonstrates the structure and boolean values for accepted payment methods in a GunBroker listing. Note that 'SeeItemDesc' and 'FreedomCoin' are deprecated.

```json
{
    "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
}
```