What's happening?

We will be deploying version 2 of the AmmoReady API (and retiring version 1 at the same time) during an upcoming scheduled maintenance window. The exact date and time of the maintenance window is TBD based on feedback from our partners. Our goal is to have this completed no later than Sunday, August 16th.

Why is API V1 being retired?

This update coincides with a change to the AmmoReady data-model that adds support for dealer-specific Categories. V1 of the API does not support this new architecture.

Dealer-specific categories

Currently, AmmoReady merchants are limited to a pre-defined (canonical) list of Categories and sub-Categories maintained by us. In May of this year, we released a new feature that allows merchants to rename and reorder these Categories, but this new functionality was (and is) limited to that default list of Categories maintained by AmmoReady. This update, and new version of the API, will allow merchants to create their own custom Categories and sub-categories and assign products to them. This is a critical feature that is part of a broader effort to dramatically enhance the capabilities of the AmmoReady platform.

What this means for you

Because of the changes being made to our data-model, V1 of the API will be disabled at the same time that V2 is deployed. In order to maintain data integrity, all active integrations will need to do the following during the upcoming maintenance window, or immediately thereafter.

Required changes for all integration partners:

Change the API URL you are using from v1 to v2
Update any stored category IDs (or strings) to reflect the new, dealer-specific values that will be returned by V2 after the maintenance window. This may require changes to the way you handle values returned by the /categories and/or /inventory endpoints. V2 returns the legacy value(s) along with the new values to make this as easy as possible (see below).

Changes to the Categories and Inventory endpoints

Categories

The /categories endpoints will now return merchant-specific categories. Since this will mean a different set of IDs being returned to you than what you would have received before, we've updated the structure of the JSON object that's returned accordingly:

[
  {
    "id": 4000,
    "parent_category_id": null,
    "canonical_category_id": 1,
    "name": "Handguns",
    "slug": "handguns",
    "subcategories": [
      {
        "id": 4001,
        "parent_category_id": 4000,
        "canonical_category_id": 4,
        "name": "Lever Action",
        "slug": "lever-action",
        "subcategories": []
      },
      {
        "id": 4002,
        "parent_category_id": 4000,
        "canonical_category_id": 5,
        "name": "Derringer",
        "slug": "derringer",
        "subcategories": []
      }
    ]
  }
]

The id attribute is the ID of the merchant-specific category. The parent_category_id attribute is the ID of the parent of a merchant-specific category, if applicable. The canonical_category_id attribute is the ID of the original canonical category (maintained by AmmoReady) that you would have received from the V1 API. This is to help you with mapping on your end from the old values to the new values.

Inventory

The /inventory endpoints will now return merchant-specific category IDs on the JSON object for an inventory item, as products will now be associated with merchant-specific categories instead of canonical categories.

Here is an example of the category-specific attributes that you would have received on V1 for an inventory item:

{
  ... ,

  "category": "Handguns",
  "subcategory": "Semi-Automatic",

  ... ,
}

And here are the attributes that you will now receive as part of V2:

{
  ... ,

  "category_id": 4500,
  "category_name": "Handguns / Semi-Automatic",

  ... ,
}

You will notice that there is only a single category_id attribute instead of separate category_id and subcategory_id attributes. There is a reason for this, which brings me to the next category-specific change for the /inventory endpoints.

You now only have to provide a single attribute, category_id, when creating a new inventory item or updating an existing inventory item, and we will automatically assign the top-level category accordingly. For example: if you provide us with the ID for a category named "Semi-Automatic", we'll know (and assign appropriately) whether that should go under "Handguns", "Rifles", or "Shotguns".

PLEASE NOTE: Yes, since we're automatically assigning the top-level category, this means that the category_id value will technically be a sub-category. However, since what you're actually providing is the ID of a single category object returned from the /categories endpoint, we felt that this naming convention made the most sense.

Other new features in V2

Product Variants

Product Variants is a new feature that was released in December 2019. V2 of the API adds full support for Product Variants.

Add Catalog Items to Inventory

AmmoReady merchants have always been able to add items from their distributor catalogs to their inventory using the "Add to Inventory" button on the product detail page. This function copies product data from the catalog to inventory, saving time and preventing data entry errors. It was designed as a quick an easy way to add and keep track of in-stock inventory. You can now do the same thing via the API with the catalog/:upc/add_to_inventory method. You can then edit items added to inventory using additional API calls to adjust quantity and/or other attributes.