1. CORE CONCEPTS & GUIDES
  2. >
  3. GUIDES
  4. >
  5. Vendor Inventory Services Implementation Guide

Overview

This guide is intended to walk you through the core functionalities of the Vendor Inventory Service (VIS) API. This includes creating Purchase Orders (POs), attaching Shipping Notices to created POs, and creating/receiving Return Merchandise Authorizations (RMAs) for partner companies running RQ. For a full list of features, see our VIS API page.

Who Is This Guide For?

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

Environment

iQmetrix provides you with two environments, Sandbox and Production.

Name Description URL
Sandbox Used for testing your API and end-to-end testing https://apirc.iqmetrix.net/vendorinventory/v1
Production Used for live operations https://api.iqmetrix.net/vendorinventory/v1

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.

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 provided credentials.
  2. Navigate to Settings > Vendor Replenishment Setup.
    • Vendor Replenishment Setup
  3. Once the Vendor Replenishment Setup screen is presented, click the Company Name (in Pending status) that you wish to enable.
  4. When the Vendor Invite Response pop-up is presented, select the user(s) that you need to have access to the select Company’s data through the Vendor Services APIs (Note: if you are not aware which of your users would need access at this point, this step can be skipped. However, use of this API will not be available until this step is completed).
  5. Select Activate Account.
    • Activate Account
  6. The Vendor-Company relationship is successfully created.
    • Success

Set-up

Step 1 - Authentication

In order to make authorized requests to the Vendor Services API, you need a username and password. These credentials are provided in your Onboarding Package.

Step 2 - Get List of Enabled Companies

To access RQ data for a company you must first determine that company’s CompanyId.

You can obtain a list of all companies enabled for you to access, use Get Enabled Companies and the following path parameters:

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": 14146, /** This will be used as CompanyId in subsequent calls **/
        "name": "Kentel"
    }
]

Note: If a company does not appear in the response, it usually means that iQmetrix has not received a signed agreement from the company allowing you to access their data.

Step 3 - Get List of Enabled Locations

To create a Purchase Order or pull inventory reports for a store, you must first determine that store’s LocationId.

You can obtain a list of all enabled locations (stores) for a company using Get Enabled Locations and the following path parameters:

Example Request

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

Example Response

HTTP 200 Content-Type: application/json

[
    {
        "companyId": 14146,
        "locationId": 14912,    /** This will be used as LocationId in subsequent calls **/
        "billToStore": 14912,
        "shipToStore": 14912,
        "name": "Summerfield",
        "address": "Suite 505",
        "city": "Springfield",
        "provinceState": "CA",
        "postalZipCode": "90210",
        "country": "United States",
        "phoneNumber": "5555555555"
    }
]

Optional - Run a Report

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

Name Description
Inventory Report Reports on inventory details for a store and date range
Inventory Adjustments Report Reports on inventory adjustments for a store and date range
Received Purchase Order Report Reports on inventory received on Purchase Orders for a store and date range
Transfer Order Details Report Reports on inventory transfers for a store for a date range
Product Sales Report Reports on product sale data for a store and date range

Example Request - Inventory Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/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

[
    {
        "globalProductId": 28,
        "productName": "iPhone 5",
        "rqProductSku": "ASCLLG000005",
        "locationId": 14912,
        "vendorSku": "JOHNSSKU678",
        "categoryPath": " >> Activations (Price Sheets) >> 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/14146/locations/14912/reports/adjustmentsStartDate=2020-01-01&EndDate=2020-05-02
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"
            }
        ]
    },
    ...
]

Example Request - Receiving Details Report

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/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 - Transfer Order Details Report

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

Example Response - Transfer Order Details Report

HTTP 200 Content-Type: application/json

 [
    {
        "shipFromLocationId": 14142,
        "shipToLocationId": 14913,
        "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/14146/locations/14912/productsales?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"
            }
        ]
    },
    ...
]

Purchase Orders

The Purchase Orders (PO) endpoints are used to add incoming inventory from a Supplier/Vendor to a location in RQ.

Create a Purchase Order

Asynchronously create a Purchase Order using Create a Purchase Order and the following path parameters:

For the request body, you must provide the following values:

The following values can be provided in the request body but are completely optional:

Note that a successful response does not guarantee successful Purchase Order creation, it only indicates that the creation request was successfully received. You must use the returned checkStatusEndpoint endpoint to verify the Purchase Order Creation Status. This is expanded more in the next step Check PO Creation Status.

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14912/purchaseOrders
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "vendorEntityId": 5123,
    "estimatedArrivalDate": "2020-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/14146/locations/14912/purchaseOrders/8844fceb-5016-4aad-bd92-3cd2e97effd7/status",
    "purchaseOrderId": "8844fceb-5016-4aad-bd92-3cd2e97effd7"   /** This will be used as PurchaseOrderId in subsequent calls **/
}

Check PO Creation Status

Check the status of the Purchase Order to determine if there were any errors with validation using Get Purchase Order Creation Status and the following path parameters:

A PO’s creation status can be one of the following:

Example Request

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14192/purchaseOrders/8844fceb-5016-4aad-bd92-3cd2e97effd7/status
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response

HTTP 200 Content-Type: application/json

{
    "status": "FailedValidation",
    "errors": [
        "ValidationProductErrors: {\"\":[\"ProductVendor combination unavailable\"]}",
        "ValidationOtherErrors: {}"
    ]
}

To see the rest of Purchase Order features, see Purchase Order Operations and Purchase Order Products.

Attach Shipping Notice to Purchase Order

Attach a shipping notice to the Purchase Order using Create a Shipping Notice for a Purchase Order and the following path parameters:

For the request body, you must provide the following values:

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14912/shippingNotices
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "purchaseOrderGuid": "8844fceb-5016-4aad-bd92-3cd2e97effd7",
    "shipmentNumber": "SSN-6114",
    "vendorSku": "JOHNSSKU678",
    "serialNumbers": [
        "SN-001",
        "SN-002",
        "SN-003"
    ]
}

Example Response

HTTP 200 Content-Type: application/json

{
    "shippingNoticeId": "25aac863-fe0f-48c3-a645-443fa2ae00ef"
}

You can verify the created Shipping Notice/s by using Get a Shipping Notice and the returned shippingNoticeId for the path parameter.

Return Merchandise Authorization (RMA)

Overview

The following section contains contextual information on how RMAs are handled in RQ and subsequently, in VIS.

Action

RMAs in the context of RQ are divided into the following:

Before creating an RMA, determine which of the above applies the most to the RMA that you will be creating through this API.

Status

RMAs in the context of RQ can have one of the following status:

Flow

The expected flow of RMAs can be summarized into the following:

  1. Create the RMA.
  2. Make changes to the RMA as needed.
  3. Commit the RMA if it hasn’t been committed.
  4. Ship the RMA.
  5. Receive all the products in the RMA.
  6. RMA gets completed.

Create an RMA

Asynchronously create an RMA using Create an RMA and the following path parameters:

For the request body, you must provide the following values:

The following values can be provided in the request body but are completely optional:

Note that a successful response does not guarantee successful RMA creation, it only indicates that the creation request was successfully received. You must use the returned checkStatusEndpoint endpoint to verify the RMA Creation Status. This is expanded more in the next step Check RMA Creation Status.

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14912/rmas
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "vendorRMANumber": "SVRMA-123",
    "comments": "Sample RMA comments",
    "committed": false,
    "products": [
        {
            "vendorSku": "JOHNSSKU678",
            "vendorInvoiceNumber": "SVIN-123",
            "actionTaken": "Credit",
            "serialNumber": "SN-003",
            "totalQuantity": 1,
            "nonSellableQuantity": 0
        }
    ]
}

Example Response

HTTP 200 Content-Type: application/json

{
    "checkStatusEndpoint": "v1/vendors/5123/companies/14146/locations/14912/rmas/4cb1dbd2-0082-46b4-a28e-b6c184405f5b/status",
    "rmaId": "4cb1dbd2-0082-46b4-a28e-b6c184405f5b"     /** This will be used as RmaId in subsequent calls **/
}

Check RMA Creation Status

Check the status of the RMA to determine if there were any errors with validation using Get RMA Creation Status and the following path parameters:

An RMA’s creation status can be one of the following:

Example Request

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14192/rmas/4cb1dbd2-0082-46b4-a28e-b6c184405f5b/status
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response

HTTP 200 Content-Type: application/json

{
    "status": "Created",
    "errors": []
}

Optional - Edit Products in the RMA

If the RMA created was created in a non-committed state ("committed": false), you can add/edit/remove products in an RMA using the RMA Products endpoints and the following path parameters:

Optional - Delete an RMA

If the RMA created was created in a non-committed state ("committed": false) and issues were found, you can delete an RMA using Delete an RMA and the following path parameters:

Note that RMAs can only be deleted while in a pending (non-committed) state.

Commit an RMA

Once a non-committed RMA is finalized, you can commit the RMA using Commit RMA and the following path parameters:

For the request body, you must provide the following value:

The following values can be provided in the request body but are completely optional:

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14192/rmas/4cb1dbd2-0082-46b4-a28e-b6c184405f5b/commit
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "vendorRMANumber": "SVRMA-123",
    "wayBillNumber": "SWBN-0184",
    "shippingMethod": "Regular",
    "shippingCost": 9.99,
    "comments": "Sample Commit Comments"
}

Example Response

HTTP 204 No Content

Ship an RMA

Change an RMA status to shipped using Ship RMA and the following path parameters:

For the request body, you must provide the following value:

The following values can be provided in the request body but are completely optional:

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14192/rmas/4cb1dbd2-0082-46b4-a28e-b6c184405f5b/ship
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "vendorRMANumber": "SVRMA-123",
    "wayBillNumber": "SWBN-0184",
    "shippingMethod": "Regular",
    "shippingCost": 9.99,
    "creditInvoiceNumber": "SCIN-0184",
    "receivingComments": "Sample Receiving Comments"
}

Example Response

HTTP 204 No Content

Receive an RMA

Receive an RMA using Receive RMA and the following path parameters:

For the request body, you must provide the following values:

The following values can be provided in the request body but are completely optional:

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14192/rmas/4cb1dbd2-0082-46b4-a28e-b6c184405f5b/receive
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "products": [
        {
            "vendorSku": "JOHNSSKU678",
            "actionTaken": "Credit",
            "serialNumber": "SN-003",
            "quantityReceived": 1,
            "unitCostCredited": 549.99
        }
    ],
    "vendorRMANumber": "SVRMA-123",
    "wayBillNumber": "SWBN-0184",
    "shippingMethod": "Regular",
    "shippingCost": 9.99,
    "creditInvoiceNumber": "SCIN-0184",
    "receivingComments": "Sample Receiving Comments"
}

Example Response

HTTP 204 No Content

Once all of the products in an RMA is received, it is deemed as Completed and will be closed.

Transfers

The Transfers endpoints are used to transfer existing inventory from one location to another.

Create a Transfer Request

Asynchronously create a Transfer Request order using Create a Transfer Request and the following path parameters:

For the request body, you must provide the following values:

The following values can be provided in the request body but are completely optional:

Note that a successful response does not guarantee successful Transfer Request creation, it only indicates that the creation request was successfully received. You must use the returned checkStatusEndpoint endpoint to verify the Transfer Request Creation Status. This is expanded more in the next step Check Transfer Request Creation Status.

Example Request

POST https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14912/purchaseOrders
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json

{
    "shipFromLocationId": 14197,
    "shipToLocationId": 14192,
    "transferProducts": [
        {
            "vendorSku": "JOHNSSKU678",
            "quantity": 2
        }
    ],
    "transferCommitted": true,
    "requestingComments": "Transfer Request is final.",
}

Example Response

HTTP 200 Content-Type: application/json

{
    "checkStatusEndpoint": "v1/vendors/5123/companies/14146/locations/14912/transfers/53c1e025-3154-4ac0-bb96-d0b52b098d2e/status",
    "transferId": "53c1e025-3154-4ac0-bb96-d0b52b098d2e"   /** This will be used as TransferId in subsequent calls **/
}

Check Transfer Request Creation Status

Check the status of the Transfer Request to determine if there were any errors with validation using Get Transfer Request Creation Status and the following path parameters:

A Transfer Request’s creation status can be one of the following:

Example Request

GET https://apirc.iqmetrix.net/vendorinventory/v1/vendors/5123/companies/14146/locations/14192/transfers/53c1e025-3154-4ac0-bb96-d0b52b098d2e/status
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response

HTTP 200 Content-Type: application/json

{
    "status": "Created",
    "errors": []
}

To see the rest of Transfer Request endpoints, see Transfers section.