Purchase Order Guide

This guide describes how to create a purchase order in RQ using the Purchase Order API.

Before you Begin

Ensure your RQ database meets the following criteria:

If you are unsure if your RQ database meets these requirements, consult with your account manager or API Launch Specialist.

Steps

Step 1 - Authenticate with iQmetrix APIs

To make requests to iQmetrix APIs, you must first generate an Access Token using the access credentials from your onboarding package.

For more information on onboarding packages, authentication and how to generate an access token, see Authenticating with iQmetrix APIs.

Step 2 - Get Location Identifiers

Every purchase order you create must specify the Entity Manager identifier for the store that is ordering the purchase order (OrdererStoreEntityId), receiving the purchase order (ReceiverStoreEntityId) and being billed for the purchase order (BillToStoreEntityId).

Retrieve a list of locations in your company using Get All Locations for A Company and the parameters:

From the response, extract the Id of one or more stores. For this example, we will use Dufferin Mall (14192) as the store that is ordering, receiving and being billed for the purchase order.

Example Request

GET https://entitymanagerrc.iqmetrix.net/v1/Companies(14146)/Locations
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json
[
  {
    "Id": 14192,
    "Name": "Dufferin Mall",
    "DisplayName": "Dufferin Mall",
    "Description": "This Location is used to clear out discounted inventory",
    "Roles": [
      "Company"
    ],
    "CreatedUtc": "2015-02-26T00:03:01.372Z",
    "LastModifiedUtc": "2015-02-27T00:03:06.392Z",
    "Area": {},
    "Address": {
      "AddressLine1": "4970 Hillside Avenue",
      "AddressLine2": "Apt 115",
      "City": "Edmonton",
      "StateCode": "ON",
      "StateName": "Ontario",
      "CountryCode": "string",
      "CountryName": "Canada",
      "Zip": "P9H 9I4"
    },
    "Attributes": {},
    "ClientEntityId": "",
    "Contacts": [],
    "Geography": {},
    "Relationships": [],
    "SortName": "dufferin mall",
    "StoreHours": {},
    "StorePhoneNumbers":[],
    "TimeZone": {},
    "Version": 13,
    "CorrelationId": "",
    "LocationType": "",
    "LocationSubType": "",
    "Logo": {},
    "Role": "",
    "TypeId": 0,
    "Website": ""
  }
]

(Optional) Step 3 - Get Employee Identifier

You can specify the User Manager identifier for the employee that made the purchase order (OrderedByEmployeeEntityId). If no value is provided, the value will default to the ID of the RQ Service User (-99).

Retrieve a list of all Users using Get All Users for an Entity and the following parameters:

Note that this endpoint is paginated, and will show the first 50 results by default. To parse the rest of the results, use $skip and $top. For example, to get the next 100 results after the first 50, use $skip=50 and $top=100.

From the response, extract the Id of a User. For this example, we will use John Bates (2576) as the employee making the purchase order.

Example Request

GET https://usermanagerrc.iqmetrix.net/v1/Entities(14146)/Users
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json
{
  "_links": {
    "prev": "string",
    "next": "string",
    "self": "/v1/Entities(14146)/Users?$skip=0&$top=50"
  },
  "_metadata": {
    "count": 1,
    "skip": 0,
    "top": 50
  },
  "items": [
    {
      "Id": 2576,
      "FirstName": "John",
      "LastName": "Bates",
      "UserName": "john@kentel.com",
      "Email": "john@kentel.com",
      "ParentEntityId": 14146,
      "ParentEntityName": "Kentel",
      "CorrelationId": "",
      "ClientUserId": "",
      "JobTitle": "",
      "Address": {},
      "Picture":{},
      "PhoneNumbers": [],
      "Profiles": [],
      "Attributes": {},
      "Version": 1,
      "IsActive": true
    }
  ]
}

(Optional) Step 4 - Get Customer Identifier

If you want to ship the purchase order to a customer, you can specify the CRM identifier for a customer (CustomerId).

Search for the customer using Search for a Customer and the following parameters:

Note that this endpoint is paginated, and will show the first 50 results by default. To parse the rest of the results, use $skip and $top. For example, to get the next 100 results after the first 50, use $skip=50 and $top=100.

From the response, extract the Id of a Customer. For this example, we will use Jane Doe (659c2a38-d083-4421-9330-46d779702f85) as the customer the purchase order should be shipped to.

Example Request

GET https://crmrc.iqmetrix.net/v1/Companies(14146)/CustomerSearch?$filter=Criteria eq 'Jane Doe'
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json
[
  {
    "Criteria": "Jane Doe",
    "Id": "659c2a38-d083-4421-9330-46d779702f85",
    "PrimaryName": "Jane",
    "MiddleName": "",
    "FamilyName": "Doe",
    "AlternateName": "",
    "CustomerType": "Person",
    "CustomerTypeId": 1,
    "DateOfBirth": "1952-07-23T12:00:00.000",
    "Disabled": true,
    "DoNotContact": true,
    "Notes": "",
    "Title": "Ms",
    "Version": 1,
    "ReferralSource": "",
    "PricingGroupId": 4125,
    "MergedIntoCustomerId": null,
    "LastModifiedDateUtc": "2018-05-29T32:16:03",
    "UniqueIdentifier": "5003000000D8cuI",
    "Addresses": [
      {
        "Id": "a08b0640-606a-41f0-901a-facaf50e75dd",
        "CustomerId": "659c2a38-d083-4421-9330-46d779702f85",
        "AddressType": "Home",
        "AddressTypeId": 2,
        "AttentionTo": "",
        "Country": "United States",
        "CountryCode": "US",
        "Default": false,
        "DoNotContact": true,
        "Email": "",
        "Locality": "Mountain View",
        "Notes": "",
        "Phone": "(555) 555-5555",
        "PostalCode": "90210",
        "PostOfficeBoxNumber": "",
        "State": "California",
        "StateCode": "US-CA",
        "StreetAddress1": "1600 Main St",
        "StreetAddress2": "",
        "Version": 1
      }
    ],
    "ContactMethods": [],
    "CustomerExtensions": [],
    "MemberOf": [],
    "RelatedCustomers": [],
    "Documents": [],
    "MergedCustomers": []
  }
]

Step 5 - Create a Purchase Order

Create a purchase order using Create a Purchase Order and the following parameters.

Parameter Name Notes Example
CompanyId Provided in Onboarding Package. 14146
VendorEntityId Provided in Onboarding Package. 92910
PurchaseOrderGuid You must generate a unique guid that will be used by RQ. <GUID>
ShippingCost Cost to ship the purchase order, must be a positive value - 0 is acceptable. 9.52
OrdererStoreEntityId The store ordering the purchase order, from Step 2. 14192
ReceiverStoreEntityId The store receiving the purchase order, from Step 2. 14192
ShippingMethod Shipping method. For a list of acceptable values, see Create a Purchase Order. Regular
EstimatedArrivalDate Estimated arrival date in the format YYYY-mm-dd. 2019-08-19
BillToStoreEntityId The store to be billed for the purchase order, from Step 2. 14192
Products.Quantity Amount of this product to be ordered. 1
Products.VendorSKU Vendor SKU VA-2249932
Committed Use true to commit the purchase order in RQ, otherwise use false. false
OrderedByEmployeeEntityId (Optional) The employee that ordered the purchase order, from Step 3. If not provided, the ID of the RQ service order will be used (-99) by default. 2576
CustomerId (Optional) The identifier of the customer the purchase order should be shipped to, from Step 4. 659c2a38-d083-4421-9330-46d779702f85
ReferenceNumber (Optional) Providing a unique value here will allow you to find the purchase order in RQ using the “scan anywhere” feature TESTPO123

A HTTP 200 response indicates the purchase order was created in RQ.

Example Request

POST https://apirc.iqmetrix.net/rqpurchaseorders/Companies/14146/PurchaseOrders
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Content-Type: json
{
  "VendorEntityId": 92910,
  "PurchaseOrderGuid": "<GUID>",
  "ShippingCost": 9.52,
  "OrderedByEmployeeEntityId": 2576,
  "OrdererStoreEntityId": 14192,
  "ReceiverStoreEntityId": 14192,
  "ShippingMethod": "Regular",
  "EstimatedArrivalDate": "2019-08-19",
  "BillToStoreEntityId": 14192,
  "Products": [
    {
      "VendorSKU": "VA-2249932",
      "Quantity": 1
    }
  ],
  "CustomerId": "659c2a38-d083-4421-9330-46d779702f85",
  "Committed": false,
  "ReferenceNumber": "TESTPO123" 
}

Example Response

HTTP 200 Content-Type: application/json

(Optional) Step 6 - Update Purchase Order

Once created, purchase orders must be updated in RQ. For more information about updating Purchase Orders in RQ, see Inventory - Purchase Orders - Updating Purchase Orders.

Update PO Screen

Next Steps

Now that you have created a purchase order in RQ, you might be interested in:

Troubleshooting

This section provides steps to resolve common problems encountered when using the Purchase Order API.

Shipping Method Missing in Update Purchase Order Screen

If you load a purchase order created through the Purchase Order API into the Update Purchase Order Screen in RQ, the value shown in the Shipping Method dropdown may be blank.

This is because the text that appears in the Shipping Method dropdown depends on the localization status of the value used for the ShippingMethod property when the purchase order is created.

Non-Localized values will always appear in the Shipping Method dropdown as provided. For example, a purchase order created with "ShippingMethod": "Fed Ex" will have “Fed Ex” in the dropdown for all users, as shown below.

Localized values will only appear in the Shipping Method dropdown if the user is logged into RQ with the appropriate language. For example, a purchase order created with "ShippingMethod": "Regular" will have “Regular” in the dropdown for a user logged into RQ with an English session but will have an empty string in the dropdown for a user logged into RQ with a French session, as shown below.


English Session - Fed Ex Shipping Method

Fed Ex English

French Session - Fed Ex Shipping Method

Fed Ex French

English Session - Regular Shipping Method

Regular English

French Session - Regular Shipping Method

Regular French

Shipping Method Localization Status

Shipping Method Status
Regular Localized
Checker Non-Localized
Rush Non-Localized
Purolator Non-Localized
UPS Non-Localized
Bus Localized
Mail Localized
Fed Ex Non-Localized
Pick Up Localized
Loomis Non-Localized
Over Night Localized
ATS Non-Localized
Other Localized

Error in RQ Database ProductVendorCombinationUnavailable

This error occurs when the products or vendors are not configured properly.

The purchase order API requires products in RQ to either be mapped to a product library product with a corresponding Vendor SKU or created as a private product with a corresponding Vendor SKU.

To determine if your product is mapped appropriately, follow the steps below.

  1. Ensure the Vendor you are using is Mapped to Entity Manager.
    • Within RQ, navigate to Settings -> Vendor Setup.
    • Ensure the Vendor you want to use is Enabled and Mapped (has both green and blue check marks).
  2. Ensure the product has the correct Vendor SKU in RQ.
    • Within RQ, locate the product in the Inventory console.
    • Ensure the product shows a blue checkmark in the top right corner with the text Mapped to Product Library.
    • Navigate to the Purchasing tab.
    • Ensure the Vendor you want to use is listed with the appropriate Vendor SKU.
  3. Ensure your product is synced to the Catalog API from Hub.
    • Within Hub, navigate to My Catalog.
    • Locate your product.
    • Ensure the Vendor you want to use is listed under the Supplier SKUs section with the appropriate Vendor SKU and Supplier (Vendor).
  4. (Optional) Ensure your product is synced to the Catalog API using APIs.