Table of Contents

Retailer API Documentation

Introduction

The Retailer API lets you manage your product listings, retrieve product information, and perform various operations related to your retail business on the GunNabber platform.

Currently, the API supports managing your product listings, including creating, updating, retrieving, and deleting products.

Authentication

To use the Retailer API, you must authenticate using your primary or alternate API keys. These two keys allow you to rotate keys without downtime.

Additionally, a test key is available for development and testing purposes, which does not affect your live product listings.

You can find your keys by navigating to Company -> API Keys.

Include your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

Important Note:

Be sure to keep your API keys secure and do not share them publicly. Additionally, be aware that rotating keys will cause the existing key you are rotating to no longer work. Ensure you update your application with the alternate key before rotating (or primary if you are currently using your alternate key).

An example workflow would be:

  1. Verify the key you are currently using is the primary or alternate key
  2. Switch your application to use the key you are NOT using. For example, if you are using the primary key, switch to the alternate key.
  3. Rotate the key you switched from. This will make the key you were previously using no longer valid.

Base URL and Versioning

The base URL for the Retailer API is:

https://api.gunnabber.com/

The API is versioned. You can specify the version in the URL or alternatively use the default version by not specifying the version For example, to access version 1 of the API, use:

https://api.gunnabber.com/v1/{endpoint}

Quick Start

To get started with the Retailer API, follow these steps:

  1. Authenticate: Use your API key in the Authorization header.
  2. Make a Request: Use the appropriate endpoint to perform the desired operation.
  3. Handle the Response: Check the response for success or error messages.
curl -X GET "https://api.gunnabber.com/v1/products" -H "Authorization: Bearer {Your Api Key}"

GunNabber Retailer client Nuget Package

We have created a .NET client library for the GunNabber Retailer API, which simplifies the process of interacting with the API. This client library is available as a NuGet package named GunNabber.RetailerApi.Client.

The Nuget package provides a convenient way to interact with the Retailer API. It includes strongly-typed models and service abstractions for managing products.

Implementing the client is straightforward:

Install via NuGet Package Manager:

dotnet add package GunNabber.RetailerApi.Client

Or via the NuGet UI in your code editor of choice.

1. Configure API Client Options

var options = new ApiClientOptions
{
    ApiKey = "your-api-key",
    ApiVersion = "1"
};

2. Initialize the Client

var client = new GunNabberClient(options);

3. Access Product Services

var productService = client.GetProductService();

4. Fetch Products

var response = await productService.GetProductsAsync();
if (response.IsSuccess)
{
    var products = response.Data;
    // Use products
}
else
{
    Console.WriteLine($"Error: {response.ErrorMessage}");
}

Models

  • Product: Represents a product in the retailer system.
  • ProductRequest: Used for creating or updating product data.
  • Response: Standardized API response wrapper.

API Response Handling

All service methods return a Response object, which includes:

  • Data: The result data (if successful)
  • StatusCode: HTTP status code
  • Headers: Response headers
  • RawContent: Raw response content
  • IsSuccess: Indicates if the request was successful
  • ErrorMessage and Errors: Error details (if any)

Endpoints

GET /products

Retrieve your full product listing.

GET /v1/products
Authorization: Bearer {Your Api Key}
Content-Type: application/json

POST /products

Create a new product listing.

POST /v1/products
Authorization: Bearer {Your Api Key}
Content-Type: application/json

{
    "gid": "548a1b5a-5b1e-4e68-923e-a071711e5fb9",
    "productType": "ammunition",
    "productName": "Federal HST 9mm Luger 124 Grain JHP",
    "description": "High-performance self-defense ammunition designed for reliability and stopping power.",
    "brand": "Federal",
    "price": 29.99,
    "upc": 123456789012,
    "mpn": "P9HST1",
    "sku": "FED-P9HST1",
    "url": "https://example.gunnabber.com/products/federal-hst-9mm",
    "availability": "in stock",
    "shippingInfo": "Ships within 2-3 business days",
    "caliber": "9mm Luger",
    "quantity": 50,
    "purchaseLimit": 5,
    "casing": "brass",
    "condition": "new",
    "grain": 124,
    "shellLength": "",
    "shotSize": "",
    "minimumPurchase": 1,
    "rebate": "",
    "make": "",
    "model": "",
    "firearmType": "",
    "action": "",
    "imageUrl": "https://example.gunnabber.com/images/federal-hst-9mm.jpg"
}

GET /products/{id}

Retrieve a specific product by ID.

GET /v1/products/{id}
Authorization: Bearer {Your Api Key}
Content-Type: application/json

PUT /products/{id}

Update an existing product by ID.

PUT /v1/products/{id}
Authorization: Bearer {Your Api Key}
Content-Type: application/json

{
    "gid": "548a1b5a-5b1e-4e68-923e-a071711e5fb9",
    "productType": "ammunition",
    "productName": "Federal HST 9mm Luger 124 Grain JHP",
    "description": "High-performance self-defense ammunition designed for reliability and stopping power.",
    "brand": "Federal",
    "price": 29.99,
    "upc": 123456789012,
    "mpn": "P9HST1",
    "sku": "FED-P9HST1",
    "url": "https://example.gunnabber.com/products/federal-hst-9mm",
    "availability": "in stock",
    "shippingInfo": "Ships within 2-3 business days",
    "caliber": "9mm Luger",
    "quantity": 50,
    "purchaseLimit": 5,
    "casing": "brass",
    "condition": "new",
    "grain": 124,
    "shellLength": "",
    "shotSize": "",
    "minimumPurchase": 1,
    "rebate": "",
    "make": "",
    "model": "",
    "firearmType": "",
    "action": "",
    "imageUrl": "https://example.gunnabber.com/images/federal-hst-9mm.jpg"
}

DELETE /products/{id}

Delete a specific product by ID.

DELETE /v1/products/{id}
Authorization: Bearer {Your Api Key}

ProductRequest Model

The Product model represents a product in the retailer system. It includes the following properties:

"ProductRequest": {
      "type": "object",
      "properties": {
        "gid": { "type": "string", "format": "uuid" },
        "productType": { "type": "string" },
        "productName": { "type": "string" },
        "description": { "type": "string" },
        "brand": { "type": "string" },
        "price": { "type": "number", "format": "double" },
        "upc": { "type": "integer", "format": "int32" },
        "mpn": { "type": "string" },
        "sku": { "type": "string" },
        "url": { "type": "string" },
        "availability": { "type": "string" },
        "shippingInfo": { "type": "string" },
        "caliber": { "type": "string" },
        "quantity": { "type": "integer", "format": "int32" },
        "purchaseLimit": { "type": "integer", "format": "int32" },
        "casing": { "type": "string" },
        "condition": { "type": "string" },
        "grain": { "type": "integer", "format": "int32" },
        "shellLength": { "type": "string" },
        "shotSize": { "type": "string" },
        "minimumPurchase": { "type": "integer", "format": "int32" },
        "rebate": { "type": "string" },
        "make": { "type": "string" },
        "model": { "type": "string" },
        "firearmType": { "type": "string" },
        "action": { "type": "string" },
        "imageUrl": { "type": "string" }
      }
    }

Example Product Model for Ammunition:

{
    "gid": "548a1b5a-5b1e-4e68-923e-a071711e5fb9",
    "productType": "ammunition",
    "productName": "Federal HST 9mm Luger 124 Grain JHP",
    "description": "High-performance self-defense ammunition designed for reliability and stopping power.",
    "brand": "Federal",
    "price": 29.99,
    "upc": 123456789012,
    "mpn": "P9HST1",
    "sku": "FED-P9HST1",
    "url": "https://example.gunnabber.com/products/federal-hst-9mm",
    "availability": "in stock",
    "shippingInfo": "Ships within 2-3 business days",
    "caliber": "9mm Luger",
    "quantity": 50,
    "purchaseLimit": 5,
    "casing": "brass",
    "condition": "new",
    "grain": 124,
    "shellLength": "",
    "shotSize": "",
    "minimumPurchase": 1,
    "rebate": "",
    "make": "",
    "model": "",
    "firearmType": "",
    "action": "",
    "imageUrl": "https://example.gunnabber.com/images/federal-hst-9mm.jpg"
}

Errors

The API uses standard HTTP status codes to indicate the success or failure of requests.

Additionally, the API may return error messages in the response body for more detailed information about the error in standardized format.

Validation errors include specific details about what went wrong, such as unsupported product types or missing required fields.

Problem Details format is used for error responses, which includes:

{
    "errors": {
        "UnsupportedProductType": [
            "Unsupported product type: testtype"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-cc44979d587ed7b83ef3658c5f653bf2-8c926d8ee8b7f583-01"
}

Rate Limits

The Retailer API has rate limits to ensure fair usage and prevent abuse. The current rate limit is:

  • 300 requests per minute

If you exceed this limit, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic in your application.

Parameter Definitions

Parameter Name Type Required Description
gid string Yes (for PUT requests) Unique identifier for the product (UUID)

Only applicable to PUT requests
productType string Yes Type of product (e.g., ammunition, firearm)

Valid types include:
ammunition, handgun, rifle, shotgun, part, accessory, optic, gear, brass, primers, bullets, powder, reloading, promotion
productName string Yes Name of the product. More descriptive is better. (i.e. Federal HST 9mm Luger 124 grain 50rd. Box)
description string No Description of the product
brand string Yes Brand of the product
price number (decimal) Yes Price of the product as a decimal. (i.e. 29.99)
upc integer No Universal Product Code (UPC) (i.e. 53457898)
mpn string No Manufacturer Part Number (MPN)
sku string No Stock Keeping Unit (SKU)
url string Yes URL to the product page
availability string Yes Availability status (e.g., in stock)

Valid availability values are (in stock, out of stock, backordered)
shippingInfo string No Shipping information
caliber string Yes (product types: ammunition, handgun, rifle, shotgun, brass, bullets) Caliber of the item
quantity integer Yes Quantity available
purchaseLimit integer No Purchase limit per order
casing string Yes (product types: ammunition, brass) Casing type (e.g., brass, steel)
condition string Yes (new, used, remanufactured) Condition of the product (e.g., new, used)
grain integer Yes (product types: ammunition, bullets) Grain weight for ammunition
shellLength string No (product types: ammunition) Length of the shell (if applicable)
shotSize string No (product types: ammunition) Shot size (if applicable)
minimumPurchase integer No Minimum purchase quantity
rebate string No Rebate information (if applicable)
make string Yes (product types: handgun, rifle, shotgun) Make of the firearm (if applicable)
model string Yes (product types: handgun, rifle, shotgun) Model of the firearm (if applicable)
firearmType string Yes (product types: handgun, rifle, shotgun)

Valid values include: (handgun, rifle, shotgun)		 Type of firearm (if applicable)
action string Yes (product types: handgun, rifle, shotgun) Action type of the firearm (if applicable)
imageUrl string No URL to the product image