Introduction

GunsAmerica selling APIs enable dealers to manage their sales by using simple REST API. In 2016 we introduced Bulk Upload, where inventory is managed by uploading a .CSV file containing the entire inventory. The new GunsAmerica APIs infrastructure provides major advancement over traditional Bulk Upload. With our new APIs dealers are able to incorporate their sales and listings from GunsAmerica into their system or their web site.

Overview

GunsAmerica selling APIs are built on the latest RESTfull and JSON technologies and are secured with OAuth 2.0 protocol.

We are using seller stock number based inventory management, which allows you to manage multiple listings by your internal stock number rather than by the listing IDs.

The Base URL for all api calls is: https://functions-prod.gunsamerica.com/

Inventory API

The inventory API allows sellers to manage their inventory on GunsAmerica web site. It allows users to post and update items to GunsAmerica web site or to the Seller Store (if there is one). Items are managed by the seller stock number instead of listing id.

Restrictions:

• Seller stock numbers can only be listed once on GunsAmerica.
• In cases where an item with the same seller stock number already exists on the seller’s account that item cannot be created/posted by the Inventory API.
• If the item that is posted by API is edited on GunsAmerica that item becomes a manual listing and cannot be updated by the Inventory API anymore.

Authentication

All GunsAmerica APIs use OAuth 2.0 protocol for application authentication and user authorization. To access our API, you will first need to obtain an access token from GunsAmerica access token service by providing your Client ID and Client secret.

All requests made to GunsAmerica REST operations require the authorization HTTP header for authentication

To obtain Client Id and Client secret you must sign up for GA API.

Obtaining OAuth access token

The request requires the following values:

• ClientID – your client id (provided to you when you sign up for the service).
• ClientSecret – Base64-encoded string (provided to you when you sign up for the service).
• OAuth scope(s) – required for access to the REST interfaces.

Access token Request example:

HTTP method: POST

URL: https://functions-prod.gunsamerica.com/api/identity/connect/token

HTTP headers:

content-type: application/x-www-form-urlencoded

Request body

grant_type:”client_credentials”

scope:”InventoryServiceAPI”

client_id:”TestSeller”

client_secret:”XXXXX-XXX-XXXX-XXXX-XXXXXXX”

Response Body

access_token:”5404d41b24a788u9khknhd0eac9360092″

expires_in:3600

token_type:”Bearer”

Inventory API Reference

GET Inventory

{{url}}/api/inventory

Returns uploaded inventory on GunsAmerica associated with the dealer account.

HEADERS

The authorization header is the only required HTTP header for this call.

RESPONSE

GET Inventory Item

{{url}}/api/inventory/{your seller stock number}

Returns an item that matches your seller stock number.

HEADERS

The authorization header is the only required HTTP header for this call.

INPUT – URI parameters

RESPONSE

RESPONSE CODES

This call returns one of the following HTTP status codes:

POST Inventory Item

{{url}}/api/inventory/

This API enables you to create (post listing) or update inventory item.

Important notes/rules:

If the same seller stock number is listed manually the item will not be created.

If you edit a listing on GunsAmerica that is created by API or bulk upload, that listing cannot be updated anymore by API/Bulk upload.

If the item has already been posted to your inventory an UPDATE will be performed. In this case the fields that are not sent and not required will not be updated. For example if you only send required fields and Item Title, only the Title (plus required fields) will be updated. Other fields will be ignored.

Once item quantity reaches 0 the listing will be made inactive.

You can create listings with limited data: UPC, Price, Seller Stock Number, & Condition. This will create listings with manufacture specification data, including descriptions and pictures. 

If UPC is not provided: Manufacturer, Model, Category ID, Caliber, Seller stock number, PictureURL, Title, Price, Quantity, Weight, Condition, and Description are required.

HEADERS

INPUT – JSON

RESPONSE CODES

This call returns one of the following HTTP status codes:

This call will return created or updated inventory items.

Status can be:

• CREATED
• UPDATED
• MANUAL
• DROP
• NO CHANGE

The returned item will also have a list of error messages if any.

POST ITEM Request example:

var settings = {

“async”: true,

“crossDomain”: true,

“url”: “http://{{url}}/api/inventory/”,

“method”: “POST”,

“headers”: {

“Content-Type”: “application/json”

},

“processData”: false,

“data”: “{

“CategoryID”: 4,

“Condition”: 2,

“Description”: “For sale is a Glock 19 gen 5 chambered in 9mm!”,

“FixedPrice” : “600”,

“MfgPartNumber” : ,

“SerialNumber” : “135686-mro997”,

“UPC” : “723175704183”,

“ShippingCost”: 19.99,

“ShippingText”:”not expensive shipping…

only $19.99″,

“Title”:”Glock 19 gen 5 w/ 3 mags and add ons!”,

“Quantity”:5,

“ShippingCost”:30,

“AddToGA”:”true”,

“AddToLSF”:”true”

}”

}

$.ajax(settings).done(function (response) {

console.log(response);

});

POST ITEM response example:

{

“ItemID”: 246266,

“ListingId”: 933227534,

“ListingStatus”: “CREATED”,

“ListingUrl”: “https://gunsamerica.com/firearms/handguns/semi-auto/Glock/19?p=3a57e6b9-6603-43db-95cf-b70f00e22985”,

“Message”: null,

“ModifiedOn”: “2017-12-29T01:24:31.567”,

“DeletedOn”: null,

“Error”: [],

“Warning”: [],

“AddToGA”: true,

“AddToLSF”: true,

“BuyNowPrice”: null,

“CategoryID”: 894,

“CategoryName”: null,

“Condition”: 2,

“ConditionDescription”: “NIB”,

“CountOfDrops”: 0,

“Description”: “For sale is a Glock 19 gen 5 chambered in 9mm!”,

“FixedPrice”: 600,

“InspectionPeriod”: 14,

“MfgPartNumber”: “glock”,

“ListingDuration”: null,

“PictureURLs”: null,

“Quantity”: 5,

“ReserverPrice”: null,

“SerialNumber”: “135686-mro997”,

“ShippingCost”: 19.99,

“ShippingText”: “not very expensive shipping… <br>only $19.99”,

“SKU”: “JRC10G3-TB/BL”,

“Title”: “Glock 19 gen 5 w/ 3 mags and add ons!”,

“UPC”: “723175704183”,

“Weight”: 0,

“WeightUnit”: 0

}

DELETE Inventory Item

{{url}}/api/inventory/{your seller stock number}

This will mark your uploaded item as deleted. Listings with the same seller stock number that are not manually listed will become inactive.

HEADERS

INPUT – URI parameters

RESPONSE

This call returns one of the following HTTP status codes:

curl -X GET "https://gunsamerica.com/api/Categories?Manufacturer=manufacturerValue&Model=modelValue&Caliber=caliberValue&Upc=upcValue" \
  -H "Authorization: Bearer <token>"

GET /api/Categories?Manufacturer=manufacturerValue&Model=modelValue&Caliber=caliberValue&Upc=upcValue HTTP/1.1
Host: api.yoursite.com
Authorization: Bearer <token>

{
  "items": {
    "0": "Collectible Firearms",
    "1": "Black Powder Muzzleloaders",
    "2": "Everything Else",
    "3": "Other Pistols",
    "4": "Semi Auto Pistols",
    "5": "Revolvers",
    "6": "Single Shot Pistols",
    "7": "Pump Action Rifles",
    "8": "Single Shot Rifles",
    "9": "Semi Auto Rifles",
    "10": "Bolt Action Rifles",
    "11": "Lever Action Rifles",
    "12": "Other Rifles",
    "13": "Pump Action Shotguns",
    "14": "Semi Auto Shotguns",
    "15": "Side By Side Shotguns",
    "16": "Other Shotguns",
    "17": "Single Shot Shotguns",
    "18": "Over Under Shotguns",
    "19": "Ammunition",
    "20": "Accessories",
    "21": "Magazines",
    "22": "Suppressor",
    "23": "NFA",
    "24": "Optics"
  }
}

{
  "error": "Unauthorized"
}

add the below for webhooks section

Webhooks

Webhooks let your application receive real-time notifications whenever key events occur in the Seller API. Instead of polling for changes, simply register an HTTP endpoint and we’ll POST payloads to you as things happen.

Supported Events

1. Registering a Webhook Endpoint

Request

POST /api/webhooks
Content-Type: application/json
Authorization: Bearer {your_jwt_token}

{
  "callbackUrl": "https://yourapp.com/api/hooks/incoming",
  "eventType": "order.created"
}

• callbackUrl (string, required): The full URL where you’ll receive HTTP POSTs.
• eventType (string, required): One of the supported event names listed above.

Response

201 Created

{
  "id": "a3f47b2e-9d14-4d93-8e75-1c2f4df1fa4c",
  "callbackUrl": "https://yourapp.com/api/hooks/incoming",
  "eventType": "order.created",
  "signingSecret": "XyZAbC123...def",
  "createdAt": "2025-07-25T18:42:00Z"
}

2. Receiving & Verifying Payloads

When your registered event fires, we POST to your callbackUrl:

POST /api/hooks/incoming HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Webhook-Timestamp: 1626873600
X-Webhook-Signature: sha256=abcdef1234567890...

{
  "event": "order.created",
  "data": {
    "orderId": "d4e5f6a7-8b9c-0d1e-2f3g-4h5i6j7k8l9m",
    "sellerId": "a3f47b2e-9d14-4d93-8e75-1c2f4df1fa4c",
    "total": 349.95,
    "items": [ … ]
  }
}

• X-Webhook-Timestamp (integer): Unix-epoch seconds; helps prevent replay attacks.
• X-Webhook-Signature (string): HMAC-SHA256 of "{timestamp}.{payload}" using your signingSecret, prefixed with sha256=.

Verifying the Signature

1. Reconstruct the string: "{X-Webhook-Timestamp}.{raw_request_body}"
2. Compute HMAC-SHA256 with your signingSecret.
3. Compare (constant-time) to the hex digest after the sha256= prefix.
4. Reject if timestamps differ by more than ±5 minutes.

3. Managing Your Webhooks

• List all: GET /api/webhooks → returns an array of your registrations.
• Get one: GET /api/webhooks/{id} → details for a specific registration.
• Delete: DELETE /api/webhooks/{id} → removes that endpoint (no more deliveries).

Best Practices

• Use HTTPS for all callbackUrls.
• Rotate your signingSecret periodically; support both old & new keys during overlap.
• Respond with 2xx quickly—if we receive non-2xx, we’ll retry with exponential backoff.
• Log both successes and failures on your side to diagnose delivery issues.

With webhooks in place, your system can react instantly to new orders, payments, and registrations—no polling required. If you have any questions or need further examples, please reach out to our developer support team.