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:

• Version 6.25 or later.
• Company Tree Sync is enabled with all locations synced.
• User Manager is enabled with all users synced to User Manager.
• Product Library is enabled.
• All vendors are mapped to Entity Manager and in Vendor Setup.
• If you want to associate purchase orders with customers, CRM sync must enabled and all customers must be mapped to CRM.
• All products added to purchase orders must either be mapped to a Product Library product with a corresponding Vendor SKU or be a private product with the corresponding Vendor SKU. For more information, see Troubleshooting.

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:

• CompanyId - Provided in Onboarding Package.

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:

• EntityId - Provided in Onboarding Package (CompanyId).

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:

• CompanyId - Provided in Onboarding Package.
• $filter - Name of the customer, for our example we will use Jane Doe.

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.

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.

Next Steps

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

• Receiving a Purchase Order

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

French Session - Fed Ex Shipping Method

English Session - Regular Shipping Method

French Session - Regular Shipping Method

Shipping Method Localization Status

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.
   • Search for your product using the request Get Catalog Items by Vendor SKU.
   • Confirm the product is configured properly using Get Product Details for a Catalog Item.