Introduction top

This API will enable you to send well formed JSON,XML, or Form Data to GunsInternational.com servers. Functions include the ability to add listings, edit listings and delete listings. We use HTML Post requests with JSON or XML payloads to integrate your listings. HTML posts also can contain FILE fields delivering your images.

Pseudocode top

To start you will need to get your Account ID and your API Token from the top of this page. When you see MY_ACCOUNT_ID in the example below that means you put in that number in place of that text. Same process for MY_API_TOKEN, put your unique api token there and replace that text.
For any language the code would look like this if you  using the XML payload option to add a listing:
Create a new variable that can hold information called payload
Add to the payload variable the following:
Set account_id = MY_ACCOUNT_ID
Set access_token = MY_API_TOKEN
Set api_task = add_listing
Set SKU = abc123
Set Category_ID = 172
Set Title = relevant title that concisely describes the listing
Set description = good description using words to help people find my listing with the search
Set price = ‘250’

Open https post request
Add payload to the form with the name ‘XML’ (this would be JSON if you were using JSON)
Add form type file named ‘image1’ and value with a pointer to my lead image ‘C:/MY_IMAGES/THIS_SKU/FULLBIG.JPG’
POST (send) the request to https://www.gunsinternational.com/api_gi/v1/xml
Wait for request
Parse the request as XML
If response success is 1 then
Go to the next listing you want to add

Here is an example using JSON to delete the Listing we just added.
Create a new variable that can hold information called payload
Add to the payload variable the following:
Set account_id = MY_ACCOUNT_ID
Set access_token = MY_API_TOKEN
Set api_task = delete_listing
Set SKU = abc123
Open https post request
Add payload to the form with the name ‘JSON’
POST (send) the request to https://www.gunsinternational.com/api_gi/v1/json
Wait for request
Parse the request as JSON
If response success is 1 then
Go to next task

Parameters top

If a required parameter is missing or if a parameter rule is broken the listing will be rejected and you will be notified of the failure in the http return, (see “return” section below). If a default is not defined for a non required parameter then the field will be ignored if it is not sent in the request. For example if you Add_listing a listing with sku “123” and set the title to “ABCD”, then you send an Update_listing with the sku equal to “123” and do not send a title parameter, the title will remain “ABCD”. If you add_listing and do not use a unique SKU your listing will be rejected.

Name	Required	Description
account_id	Required	View your account ID by clicking the “Show API Credentials” button above.
access_token	Required	View your Unique Access Token by clicking the “Show API Credentials” button above.
api_task	Required	Add_listing Update_listing Delete_listing Inventory
SKU	Required see notes	String max length of 60. Letters and numbers only. Must be unique within all of your listings. Required for all tasks except Inventory. If omitted with Inventory all your listings will be returned
Listing_type	Required see notes	Required if no Category_ID on Add_listing, MUST BE ONE OF 'Rifles' 'Shotguns' 'Pistols' 'Revolvers' 'NFA' 'Accessories'
Category	Required see notes	Required if no Category_ID on Add_listing. This is a description of the category this listing should be in, like 'Glock 19' or 'Colt Python' (See More Details)
Category_ID	Required see notes	Number. Click here for a category lookup table. You must supply this on add_listing if you do not supply a Listing_type and Category
Category_ID2	NOT Required	Number. Click here for a category lookup table
Title	Required for api_task Add_listing	150 Alpha Numeric Characters, NO HTML
Description	Required for api_task Add_listing	8000 Alpha Numeric Characters, the only HTML tags allowed are B,STRONG,BR,U,I,UL,LI, and P. All other markup will be stripped.
Price	Required for api_task Add_listing	Just numbers and an optional decimal. If you send a zero (0 or 0.00) the listing will display POR (price on request).
Featured	NOT Required Default 0	1 or 0 1 for make featured 0 for un feature. If you have the maximum featured listings this variable will be turned to 0.
active	NOT Required Default 1	1 or 0 1 is active 0 is disabled
ActionType	NOT Required	200 Alpha Numeric Characters, NO HTML
antique	NOT Required Default 0	1 or 0 1 is antique 0 is not antique
Barrels	NOT Required	200 Alpha Numeric Characters, NO HTML
BarrelLength	NOT Required	200 Alpha Numeric Characters, NO HTML
BarrelType	NOT Required	200 Alpha Numeric Characters, NO HTML
Bore	NOT Required	200 Alpha Numeric Characters, NO HTML
BoreCondition	NOT Required	200 Alpha Numeric Characters, NO HTML
Butt_Pad	NOT Required	200 Alpha Numeric Characters, NO HTML
Caliber	NOT Required	200 Alpha Numeric Characters, NO HTML
Chambers	NOT Required	200 Alpha Numeric Characters, NO HTML
Chokes	NOT Required	200 Alpha Numeric Characters, NO HTML
ChokeLeft	NOT Required	200 Alpha Numeric Characters, NO HTML
ChokeRight	NOT Required	200 Alpha Numeric Characters, NO HTML
Condition	NOT Required	200 Alpha Numeric Characters, NO HTML
ConditionMetal	NOT Required	200 Alpha Numeric Characters, NO HTML
Ejectors	NOT Required	200 Alpha Numeric Characters, NO HTML
Engraving	NOT Required	200 Alpha Numeric Characters, NO HTML
Extras	NOT Required	200 Alpha Numeric Characters, NO HTML
Finish	NOT Required	200 Alpha Numeric Characters, NO HTML
ForeEnd	NOT Required	200 Alpha Numeric Characters, NO HTML
Gauge	NOT Required	20 Alpha Numeric Characters, NO HTML
Grips	NOT Required	200 Alpha Numeric Characters, NO HTML
GunCase	NOT Required	200 Alpha Numeric Characters, NO HTML
ItemLocation	NOT Required	200 Alpha Numeric Characters, NO HTML
sale_pending	NOT Required Default 0	1 or 0 1 is sale pending 0 is not sale pending
SerialNumber	NOT Required	50 Alpha Numeric Characters, NO HTML
Sights	NOT Required	200 Alpha Numeric Characters, NO HTML
Stock	NOT Required	200 Alpha Numeric Characters, NO HTML
StockDimensions	NOT Required	200 Alpha Numeric Characters, NO HTML
StockDrop	NOT Required	200 Alpha Numeric Characters, NO HTML
StockComb	NOT Required	200 Alpha Numeric Characters, NO HTML
StockHeel	NOT Required	200 Alpha Numeric Characters, NO HTML
StockCast	NOT Required	200 Alpha Numeric Characters, NO HTML
Triggers	NOT Required	200 Alpha Numeric Characters, NO HTML
LOP	NOT Required	200 Alpha Numeric Characters, NO HTML
Manufacturer	NOT Required	200 Alpha Numeric Characters, NO HTML
MfgDate	NOT Required	20 Alpha Numeric Characters, NO HTML. Should be a date like this mm/dd/yyyy
MinWallThickness_Left	NOT Required	200 Alpha Numeric Characters, NO HTML
MinWallThickness_Right	NOT Required	200 Alpha Numeric Characters, NO HTML
Model	NOT Required	100 Alpha Numeric Characters, NO HTML
WoodCondition	NOT Required	200 Alpha Numeric Characters, NO HTML
Optic	NOT Required	200 Alpha Numeric Characters, NO HTML
Proof_Black	NOT Required	200 Alpha Numeric Characters, NO HTML
Proof_Nitro	NOT Required	200 Alpha Numeric Characters, NO HTML
relic	NOT Required Default 0	1 or 0 1 is relic 0 is not relic
Rib	NOT Required	200 Alpha Numeric Characters, NO HTML
Weight	NOT Required	200 Alpha Numeric Characters, NO HTML
buy_now	NOT Required Default 0	1 or 0 1 is buy now 0 is not buy now

Return Variables top

Return will be in XML or JSON depending on the method you use. If you send a raw form you will receive back XML. You will receive the following variables on every request. Some may be empty so make sure you code to handle that.

• Success - a 1 for success and 0 for failure
• GI_Listing_ID - this will be blank unless you are performing an “add_listing”
• SKU - this will echo back the required SKU value you posted unless an error occurred
• Message - this will be blank on success. If a failure occurred it will describe the nature of the failure.

Categories top

The recommended method of providing a "category_id" is from the GunsInternational.com cross reference table and provide the category-id for the two fields. Check the gun category list here, and the Accessories Category IDs here. 

Click here to download a CSV file that contains all the up-to-date Gunsinternational Categories so you can make your own lookup table.

Alternatively you can provide the Listing_type and Category:

Listing-type: Provide Rifles, Shotguns, Pistols, Revolvers, NFA or Accessories. If its not one of these specific listing types it will result in a unsuccessfull submission. 

Category: This is a list of words (no more that 5) that describes concisely what your listing is. Recommended: Make Model and caliber. If you review the existing categories in the category lookup table this will help you to detemine what should be included in this field. 

Hint:  Use terms that one would use to search your listing. 

Image Uploads top

You may have 25 images per listing. You will create a pointer to your image file and insert it into your https request using a form member as type FILE. Name the file imageX where X equals the order you want that image to occupy. As an example, for your lead/preview/best image use name=”image1”. The first image will show on the preview of your listing. The preview shows on the New Today, New This Week pages and also the search and category pages.

Images should be between 600px and 3,000px wide. Only files of type JPG, GIF and PNG are allowed. HEIC is not supported! If your image’s height or width is larger than 3000px it will be scaled to 3000px so pre size them to save yourself some bandwidth. Make sure your orientation is correct and make sure your image file has an extension.

If an image is rejected or has a problem the rest of your task will succeed but you will receive a zero for a success on return. So if you added a listing with one heic image, the listing will load but it will have no image. Send an update with a correct image in that case.

If you have a listing with 5 images and you send an update with a field ‘image1’ then the previous first image will be replaced with the new one. You will still only have 5 images, not 6 in this case. Make sure you update with image fields starting with ‘image6’ in this example.

If you want to delete an image then you must use the Image URL method below.

Images you Host top

If you already have your images public on the internet then we can fetch them for you. With the api_task Add_listing or Update_listing, You will add a parameter called image_urlX (where X is the order of the image (number 1-25)) containing the URL of the image. You can include 25 image url parameters. 

Follow all the same rules in the previous image uploads section. Make sure your site won't block our fetch, sometimes anti scraping protection is added to sites and if this is the case you will have to make a rule on your firewall to let us pass. Our spider will declare itself in the header userAgent as [GI_API image fetcher]. We won't be crawling your site and will only go to the exact url you specify. This fetch will have a slight delay and will not occur at the exact time you post your request. Because of this delay you may notice your listing does not have images you specified. Give it a few minutes and shift refresh the gunsinternational detail page and it will hopefully show up. 

If you want to delete an image then send an update_listing with the position of the image you want deleted with a payload of 'delete' instead of a URL. For example, if you wanted to get rid of the 6th image on your listing, send image_url6:delete (empty payloads will be ignored).

No webhooks yet, so you won't be notified when our fetch completes, or fails. If you are not seeing any images you should contact us and we will work out the issue together.

Special HTML characters top

You must translate some special characters that will cause your POST requests to fail. See the table below and programmatically change your data.

Double quote ["]	“
Single Quote [']	‘
Left wicket [<]	&#062;
Right wicket [>]	&#060;

Inventory Task top

You can use this API to return a structure containing all the details of a single listing or of all of you listings. You could use this structure to dynamically populate a separate website for your store. 

Guns International also offers branded websites showcasing only your inventory, contact support for more info. 

To return one of your listings use the following:
account_id=MY_ACCOUNT_ID
access_token=MY_API_TOKEN
api_task=Inventory
sku=sku_of_your_listing

If you send your request as XML to the XML endpoint (https://www.gunsinternational.com/api_gi/v1/xml) you will receive an XML structure back.
If you send your request as JSON to the JSON endpoint (https://www.gunsinternational.com/api_gi/v1/JSON you will receive a JSON structure back.

Return Structure:
You will receive just the info for that listing if you supplied a SKU. If you omitted the SKU you will receive a structure with every listing as the following substructure. Both will contain every parameter from the Parameters section.
SKU   

• GI_Listing_ID
• EnterDate
• ExpireDate
•  ....
• every Parameter including empty Parameters
•  ....

Using JSON top

If you are using JSON you need to post your form to https://www.gunsinternational.com/api_gi/v1/json

Your form will have one field named ‘json’ which will contain as a value your json structure. Check to make sure it is valid JSON before you send it. Invalid JSON will result in a success return of zero and no intended actions will occur.

Adding image data is the same as XML or FORM methods. See the ‘Image Upload’ section for instructions.

Watch out for double and single quotes in your data. You will need to translate these characters to html specific markup. See the special html characters section of these instructions.

Using XML top

If you are using XML you need to post your form to https://www.gunsinternational.com/api_gi/v1/xml

Your form will have one field named ‘xml’ which will contain as a value your xml structure. Check to make sure it is valid XML before you send it. Invalid XML will result in a success return of zero and no intended actions will occur.

Adding image data is the same as JSON or FORM methods. See the ‘Image Upload’ section for instructions.

Watch out for double and single quotes in your data, and wickets. You will need to translate these characters to html specific markup. See the special html characters section of these instructions.

Using Raw Form inputs top

You can build a form with multiple inputs rather than creating a XML or JSON structure. The name of the input will corespont to the parameter. For example you would have a form input named “account_id” with a value of your account id. So on with the other required fields such as access_token, api_task and SKU.

Post this form to https://www.gunsinternational.com/api_gi/v1/field

This method will return an XML payload identical to the XML method return.

Example CF/LUCEE top

<!--- Add a Listings with xml, we will add a colt python revolver with one image--->
<!--- create the xml structure --->
<cfoutput>
<cfsavecontent variable="strXML"> 
<gi_api_request>
    <account_id>REPLACE_WITH_ACCOUNT_ID</account_id>
    <access_token>REPLACE_WITH_API_CREDENTIAL</access_token>
    <api_task>Add_listing</api_task>
    <sku>REPLACE_WITH_YOUR_SKU</sku>
    <listing_type>Revolvers</listing_type>
    <category>colt python</category>
    <title>Colt Python 6 inch Nickle</title>
    <description>#XmlFormat("<b>My descriptions<br><br> with some allowed html tags formatted for xml</b>", "true")#</description>
    <price>1234.00</price>
</gi_api_request>
</cfsavecontent>
</cfoutput>
 
<!--- send the xml to Gunsinternational Servers --->
<cfhttp method="post" url="https://gunsinternational.com/api_gi/v1/xml/">
    <cfhttpparam type="formfield" name="xml" value="#strXML.Trim()#"/>  
    
    <!--- add an image for your listing from you local file system --->
    <cfhttpparam type="file" name="image1" file="PATH_TO_YOUR_LOCAL_IMAGE_FILE.JPG"> 
</cfhttp>
 
<!--- display the reply from the server --->
<cfdump var="#XmlParse(cfhttp.Filecontent)#">
<!--- example xml add done! --->



<!--- Update the Listing we just added with JSON. We will change the proce and add an additional image.--->
<!--- create the JSON structure --->
<cfset giJSON.account_id = 'REPLACE_WITH_ACCOUNT_ID'>
<cfset giJSON.access_token = 'REPLACE_WITH_API_CREDENTIAL'>
<cfset giJSON.api_task = 'Update_listing'>
<cfset giJSON.sku = 'REPLACE_WITH_YOUR_SKU'>          
<cfset giJSON.price = '5000.00'>

<cfset giJSON_var = serializeJSON(giJSON) />

<!--- send the JSON to Gunsinternational Servers --->
<cfhttp method="post" url="https://gunsinternational.com/api_gi/v1/json/">
    <cfhttpparam type="formfield" name="json" value='#giJSON_var#' /> 
    
    <!--- add an image for your listing from you local file system --->
    <cfhttpparam type="file" name="image2" file="PATH_TO_YOUR_SECOND_LOCAL_IMAGE_FILE.JPG"> 
</cfhttp>

<!--- display the reply from the server --->
<cfdump var="#deserializeJson(cfhttp.Filecontent)#">
<!--- example JSON update done! --->



<!--- Delete the listing we just added using the Raw Form Field method--->
<cfhttp method="post" url="https://gunsinternational.com/api_gi/v1/field/">
  <cfhttpparam type="formfield" name="account_id" value="REPLACE_WITH_ACCOUNT_ID">
  <cfhttpparam type="formfield" name="access_token" value="REPLACE_WITH_API_CREDENTIAL">
  <cfhttpparam type="formfield" name="api_task" value="delete_listing">
  <cfhttpparam type="formfield" name="SKU" value="REPLACE_WITH_YOUR_SKU">
</cfhttp>

<!--- display the reply from the server --->
<cfdump var="#XmlParse(cfhttp.Filecontent)#"><!--- remember you will get XML back if you use the field method --->
<!--- example FIELD delete done! --->

Example PHP with CURL top

//Add a Listings with xml, we will add a colt python revolver
//Store your XML Request in a variable
$input_xml = '<account_id>REPLACE_WITH_ACCOUNT_ID</account_id>
<access_token>REPLACE_WITH_API_CREDENTIAL</access_token>
<api_task>Add_listing</api_task>
<sku>REPLACE_WITH_YOUR_SKU</sku>
<listing_type>Revolvers</listing_type>
<category>colt python</category>
<title>Colt Python 6 inch Nickle</title>
<description>My descriptions formatted for xml</description>
<price>1234.00</price>';

$url = "https://gunsinternational.com/api_gi/v1/xml/";

//setting the curl parameters.
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS,"xmlRequest=" . $input_xml);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 300);
$data = curl_exec($ch);
curl_close($ch);

//convert the XML result into array
$array_data = json_decode(json_encode(simplexml_load_string($data)), true);

print_r('<pre>'); 
print_r($array_data); 
print_r('<pre>');