Overview

The Vendor Inventory API is in Beta and subject to change.

This guide is intended to walk you through the process of creating a Purchase Order and Purchase Order Shipment Notice in RQ through the Vendor Inventory API.

In addition, the Vendor Inventory Service APIs will allow a vendor to run product inventory reports and create purchase orders for companies running RQ.

Who Is This Guide For?

You may be interested in this guide if you are a Vendor or Supplier interested in becoming a Vendor Inventory partner.

Environment

iQmetrix provides you with two environments, Sandbox and Production.

Name Description  
Sandbox Used for testing your API and end-to-end testing https://apirc.iqmetrix.net/vendorinventory
Production Used once development is complete https://api.iqmetrix.net/vendorinventory

For more information, see Environments.

Onboarding Package

As part of the onboarding process, you will have received an onboarding package from the iQmetrix API team. This package provides you credentials and access details in order to perform the topics covered in this guide.

Should you require information beyond the scope of this guide, or did not receive the onboarding package, contact API Launch.

Enabling New Clients

Tip: A release agreement must be signed by each company before a relationship can be established. Details about the release agreement are provided in your Onboarding Package.

Clients using Vendor Replenishment services must first grant the vendor access to their company data. This is done through our HUB application.

  1. Log into HUB using the credentials provided
  2. Navigate to Settings > Vendor Replenishment Setup
    • Vendor Replenishment Setup
  3. The Vendor Replenishment Setup screen is presented. Select the hyperlink of the Company Name in Pending status
  4. When the Vendor Invite Response pop-up is presented, select the user(s) that should have access to companies data through the Vendor Inventory APIs (note: if you do not know the users at the time of activation, this step can be skipped. Although, use of APIs will not be available until the set-up is completed)
  5. Select Activate Account.
    • Activate Account
  6. HUB will save results and Activate the Vendor/Company relationship
    • Success

Steps

Step 1 - Authentication

In order to make authorized requests to the Vendor Inventory API, you need a username and password. These credentials are provided in your onboarding package.

Step 2 - Sending Products to iQmetrix

In order to have your products available to RQ, you must first send your products to be curated by iQmetrix.

The following steps describe the process of sending products to iQmetrix using the Product Feed API.

Map Classifications

iQmetrix organizes retail products in a hierarchical structure using Classification Trees.

Definition: A Classification Tree is a hierarchal structure used to represent an industry. Classification Trees are made up of Categories, which group similar products together, and Classifications which act as a template for Product information.

Each Product must have an associated Classification Tree and Classification.

For a list of Classifications, use the request Getting a Classification Tree and the following parameters:

Example Request
GET https://productlibraryrc.iqmetrix.net/v1/ClassificationTrees(1)
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Example Response
HTTP 200 Content-Type: application/json
{
    "Id": 1,
    "Name": "Cellular & Accessories",
    "IsCanonical": true,
    "Description": "iQmetrix classification of products for wireless retail",
    "Owner": null,
    "Categories": [
        {
            "Id": 2,
            "Name": "Devices",
            "Order": 1,
            "Categories": [
                {
                    "Id": 3,
                    "Name": "Phones",
                    "Order": 1,
                    "Categories": [],
                    "Classifications": []
                }
        }
    ],
    "Classifications": [
        {
            "Id": 69,
            "Name": "SIM Cards",
            "Order": 5,
            "ProductTemplate": {
                "Id": 16,
                "Name": "Wireless Device"
            }
        }
    ],
    "IsPrivate": false,
    "Version": 878
}

Map Product Details

To send product information to iQmetrix, you must map product specifications in your system to iQmetrix as Field Definitions.

Definition: A Field Definition is an object that represents a product specification, such as name or unit.

Field Definitions have two identifier properties:

Follow these instructions to map Field Definitions between Sandbox and Production Environments.

  1. Get a list of all Field Definitions from the Production Environment using the example below
  2. Search and map fields from your system to fields in the response
  3. While mapping, locate the field identifier and string identifiers from the API and add them to a configuration table
  4. Get a list of all Fields Definitions from the Sandbox Environment
  5. Search for the string identifiers to be mapped and add their corresponding field identifier to your configuration table
Example
Your Definition StringId Id (Sandbox) Id (Production)
Name Product Name 1 1
Description Long Description 40 45
Suggested Price MSRP 87 93

Field Recommendations

We recommend the following product information be sent with your products:

To get a list of Field Definitions, use the request Getting Field Definitions.

Example Request
GET https://productlibraryrc.iqmetrix.net/v1/FieldDefinitions
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Example Response
HTTP 200 Content-Type: application/json
[
    {
        "Id": 1,
        "StringId": "Product Name",
        "InputType": "TextSingleLine",
        "IsRequired": true,
        "LanguageInvariantUnit": "",
        "DisplayName": "Product Name",
        "Owner": null,
        "Unit": "",
        "LastModifiedUtc": "2016-10-05T21:16:26.572Z",
        "IsPrivate": false,
        "Options": [],
        "LanguageInvariantName": "Product Name",
        "IsArchived": false
    }
]
        

Send Products

To manage products from within the iQmetrix ecosystem, you must provide product information to iQmetrix using a Product Feed.

Definition: A Product Feed is a system that allows you to channel all of your product information into a single source within the iQmetrix system. Once curated by iQmetrix, Products on your Feed are made available to retailers through Product Library then removed from the feed.

Product information can be sent using the request Add a Product to a Feed and the following parameters:

Example Request
POST https://curationrc.iqmetrix.net/v1/ProductFeeds(5)/Products
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "VendorSkus": [
      {
        "Sku": "SMX551",
        "VendorName": "Amazon",
        "Description": ""
      }
    ],    
    "Fields": [
      {
        "Definition": {
          "Id": 93,
          "StringId": "MSRP"
        },
        "Value": "69.95 USD"
      },
      {
        "Definition": {
          "Id": 45,
          "StringId": "Long Description"
        },
        "Value": "The Defender case features three layers of defense."
      },
      {
        "Definition": {
          "Id": 1,
          "StringId": "Product Name"
        },
        "Value": "Defender Case for Apple iPad Mini 4 Black"
      }
    ],  
    "Manufacturer": "OtterBox",
    "ManufacturerSku": "77-52771",
    "ModelName": "Defender Cases for Apple iPad Mini 4",
    "UPC": "723755004337",
    "Assets": [
      {
        "AssetUrl": "http://animaliaz-life.com/data_images/cat/cat2.jpg"
      }
    ],
    "Classification": {
      "TreeId": 1,
      "Id": 4
    },
    "ClassificationTreeName": "Cellular & Accessories",
    "LastModifiedByVendorUtc": "2017-08-08T00:00:00Z"
}  
Example Response
HTTP 200 Content-Type: application/json
{
    "VendorSkus": [
        {
            "Sku": "SMX995",
            "VendorName": "Amazon",
            "Description": ""
        }
    ],    
    "Id": 2,
    "Classification": {
        "TreeId": 1,
        "Id": 4,
        "Name": "Smartphones"
    },
    "ClassificationTreeName": "Cellular & Accessories",
    "ProviderClassification": null,
    "Manufacturer": "OtterBox",
    "ManufacturerSku": "77-52771",
    "UPC": "723755004337",
    "Fields": [
        {
            "Definition": {
                "Id": 1,
                "StringId": "Product Name",
                "InputType": "TextSingleLine",
                "IsRequired": true,
                "LanguageInvariantUnit": "",
                "DisplayName": "Product Name",
                "Unit": "",
                "Options": [],
                "LanguageInvariantName": "Product Name"
            },
            "Value": "Defender Case for Apple iPad Mini 4 Black"
        }
    ],
    "Assets": [
        {
            "Id": "00000000-0000-0000-0000-000000000000",
            "FileName": null,
            "MimeType": null,
            "OriginalUrl": "http://animaliaz-life.com/data_images/cat/cat2.jpg",
            "MediaUrl": null,
            "IsConverted": false
        }
    ],
    "UnsupportedAssets": [],
    "LastModifiedByVendorUtc": "2016-03-08T00:00:00Z",
    "ModelName": "Defender Cases for Apple iPad Mini 4"
}

Step 3 - Get List of Enabled Companies

To communicate with a company using RQ you must first determine its CompanyID.

The request Getting a Company List can be used to get a list of companies to which you have an active relationship.

Example Request

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companyRelationships
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "id": 406711,
        "name": "Sam's Phone Store"
    }
]
Tip: From the response the CompanyID value 406711 will be used in the following steps.

Step 4 - Get List of Enabled Locations

To create a purchase order or pull inventory reports for a store, you must know its LocationID.

The request Get Enabled Locations is used to obtain a list of all enabled locations for a company.

Example Request

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companyRelationships/406711/locations
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "companyId": 406711,
        "locationId": 14912,
        "billToStore": 14912,
        "shipToStore": 14912,
        "name": "Summerfield",
        "address": "Suite 505",
        "city": "Springfield",
        "provinceState": "CA",
        "postalZipCode": "90210",
        "country": "United States",
        "phoneNumber": "5555555555"
    }
]
Tip: From the response the LocationId value 14912 will be used in the following steps.

Step 4 - Run a Report

To assist in determining which products need to be replenished the Vendor Inventory API provides several reports.

Name Description
Inventory Report Reports on inventory details for a store and date range
Adjustments Report Reports on inventory adjustments for a store and date range
Receiving Details Report Reports on inventory received on purchase orders for a store and date range
Transfer Details Report Reports on inventory transfers for a store for a date range
Product Sales Report Reports on product sell through data for a store and date range

Example Request - Inventory Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/406711/locations/14912/reports/inventory?StartDate=2019/06/14&EndDate=2019/06/14
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response - Inventory Report

HTTP 200 Content-Type: application/json
[
    {
        "locationId": 14912,
        "vendorSku": "JOHNSSKU678",
        "categoryPath": " >> Activations (Price Sheets) >> Verizon (Old) >> Equipment >> Phones",
        "retailPrice": 500,
        "maximumLevel": 20,
        "minimumLevel": 5,
        "minMaxLocked": false,
        "doNotOrder": false,
        "quantityInStock": 12,
        "quantityOnOrder": 1,
        "quantityTransferIn": 1,
        "quantityTransferOut": 0,
        "quantitySold": 1,
        "quantityOnUncommittedOrder": 0,
        "quantityCommittedOnOrderEntry": 0,
        "quantityOnBackorder": 6
    }
]

Example Request - Adjustments Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/406711/locations/14912/reports/adjustmentsStartDate=2019/06/14&EndDate=2019/06/14
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response - Adjustments Report

HTTP 200 Content-Type: application/json
[
    {
        "adjustmentId": "STARKIA42",
        "locationId": 14912,
        "adjustmentDate": "2019-06-14T11:57:29.19",
        "products": [
            {
                "vendorSku": "JOHNSSKU678",
                "quantity": 1,
                "serialNumber": "52342612341235",
                "adjustmentReason": "Inventory Count"
            },
            {
                "vendorSku": "JOHNSSKU345",
                "quantity": 10,
                "serialNumber": "",
                "adjustmentReason": "Inventory Count"
            }
        ]
    }
]

Example Request - Receiving Details Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/406711/locations/14912/reports/receiving?StartDate=2019/06/14&EndDate=2019/06/14
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response - Receiving Details Report

HTTP 200 Content-Type: application/json
[
    {
        "receivingId": "STARKRE24",
        "dateReceived": "2019-06-14T12:10:23.157",
        "locationId": 14912,
        "purchaseOrderId": "21a8876b-4de2-4e14-a6d5-f63a4287d064",
        "products": [
            {
                "vendorSku": "JOHNSSKU678",
                "quantity": 4,
                "serialNumbers": [
                    "3871600018412312",
                    "387600018551233",
                    "387600018562344",
                    "3876000185623425"
                ]
            },
            {
                "vendorSku": "JOHNSSKU012",
                "quantity": 3,
                "serialNumbers": [
                    "387000181312412",
                    "387600018561231",
                    "387600018551231"
                ]
            }
        ]
    }
]

Example Request - Receiving Details Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/406711/locations/14912/reports/transfers?StartDate=2019/06/14&EndDate=2019/06/14&includeShipped=true&includeReceived=true
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response - Receiving Details Report

HTTP 200 Content-Type: application/json
 [
    {
        "shipFromLocationId": 14142,
        "shipToLocationId": 14912,
        "transferId": "STARKTR6",
        "transferProducts": [
            {
                "vendorSku": "JOHNSSKU678",
                "quantity": 1,
                "shippingInfo": [
                    {
                        "serialNumber": "52342612341235",
                        "dateReceived": null,
                        "dateShipped": "2019-06-14"
                    }
                ]
            }
        ],
        "requestingComments": "",
        "shippingComments": "Shipping from Store 1 to 2",
        "receivingComments": "",
        "transferCommitted": true
    }
]

Example Request - Product Sales Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/406711/locations/14912/productsalesreport?StartDate=2019/06/14&EndDate=2019/06/14
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response - Product Sales Report

HTTP 200 Content-Type: application/json
[
    {
        "invoiceId": "STARKIN145",
        "originalInvoiceId": "",
        "invoiceDate": "2019-06-14T11:58:11.633",
        "locationId": 14912,
        "invoicedByEmployee": {
            "id": 212,
            "firstName": "John",
            "lastName": "Test"
        },
        "invoiceProducts": [
            {
                "vendorSku": "JOHNSSKU678",
                "serialNumber": "52342612341235",
                "quantity": 1,
                "price": 500,
                "invoiceAction": "Sold"
            }
        ]
    }
]

Step 5 - Create a Purchase Order

The request Create Purchase Order allows you to create a purchase order for a particular store and a set of products

Example Request

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/406711/locations/14912/purchaseOrders
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "VendorEntityId": 5123,
    "EstimatedArrivalDate": "2019/06/17",
    "VendorInvoiceNumber": "4236234",
    "Products": [
    {
      "VendorSku": "JOHNSSKU678",
      "Quantity": 1,
      "Cost": 499.99
    }
    ],
    "Committed": true,
    "ShippingCost": 1.00,
    "BillToStore": 14912,
    "ShipToStore": 14912
}

Example Response

HTTP 200 Content-Type: application/json
{
    "checkStatusEndpoint": "v1/vendors/5123/companies/406711/locations/14912/purchaseOrders/8844fceb-5016-4aad-bd92-3cd2e97effd7/status",
    "purchaseOrderId": "8844fceb-5016-4aad-bd92-3cd2e97effd7"
}

Step 6 - Check Purchase Order Status

Coming Soon

The request Check Purchase Order Status allows you to check the creation status of a purchase order. As the Create Purchase Order API requests are received asynchronously, you must verify the order was created successfully or failed.

Step 7 - Check Purchase Order Shipping Notice (Optional)

Coming Soon

The request Creating a Purchase Order Shipment Notice allows you to create a shipment notice for an existing purchase order. The shipment notice will be used when receiving purchase order products with serial numbers or SKUs.

Next Steps

Now that you have created a Purchase Order and/or Purchase Order Shipment Notice, you may be interested in the following calls.

Troubleshooting

If you encounter any errors while following this guide, see Errors.

Was this page helpful?