Punchout Integration Requirements

We are excited that you would like to integrate with us! We want to provide you with our expectations and process to get approved for production credentials. Below we lay out the minimum requirements for a quality integration that your customers will love! When you have satisfied at least these requirements, you may schedule a time to demo your integration with our team. You can schedule a demo by emailing Jake Benson at jbenson@partstech.com.

During the demo you will run us through your implementation of the requirements listed below. We will start the demo with you showing how your application directs users to the PartsTech sign up page. Then we’ll see how a user, not yet connected to PartsTech, enters their PartsTech credentials into your application to connect. From there you will continue through the list until we have seen the implementation of each requirement. Feel free to make your own copy of this checklist to help you follow the demo process.

Our team may ask questions and provide feedback during and after the demo. If your integration meets the minimum requirements for approval, then you will receive production credentials. If it is not approved, then we will communicate which requirements were not met and what to improve for approval. If you have any questions during development or about these requirements, you can reach out to Alex Keller at akeller@partstech.com.

Minimum Requirements

1. Users without a connected PartsTech account are directed to sign up

In your application, provide a link that leads to the PartsTech sign up page for users without a connected PartsTech account. The sign up link should be included in your PartsTech set up process and help documents that guide your users on connecting to PartsTech.

2. Users without a connected PartsTech account are guided on where to find their PartsTech Username and API Key

After users create their PartsTech account, they will need to use their PartsTech Username and API Key to connect to PartsTech in your application. Guiding your users to their PartsTech Username and API Key can be done in your help documentation or in your PartsTech set up process. For example, you could utilize a tooltip for guidance or to link users to help documentation that guides them more clearly and visually.

Once logged into PartsTech, the Username and API Key can be found by clicking on the Profile button in the menu on the left. We have help documentation available for this topic.

3. On the PartsTech set up page, the Username and API Key fields are labeled as “Username” and “API Key”

Where users enter their PartsTech credentials into your application to connect their PartsTech account, the two fields should be labeled “Username” and “API Key”. Labeling these two fields correctly lessens confusion for users when connecting their PartsTech account.

4. PartsTech is opened correctly, and closed when a user quotes or orders

If your application is a web application, the PartsTech punchout session should be opened in a new browser tab. If your application is a desktop application, the PartsTech punchout session should be opened in a new window or a new tab within your desktop application. For both cases, when a user submits a quote or orders items within PartsTech, that PartsTech tab or window should be automatically closed. 

5. A supported browser is used to render PartsTech

We support all major browsers, such as Chrome, Edge, Firefox, Safari, and Opera. We also support Chromium based browsers. We do not support Internet Explorer. This applies to desktop applications opening PartsTech . If you are a web application, then include our supported browsers in your help documentation and provide this information to your support team. If users are contacting your support team with PartsTech issues and they are using an unsupported browser, then those users should first be directed to use a browser that is supported by both your application and PartsTech.

6. Items are added to a repair order by sending users to a punchout session

When users want to add items to a repair order from PartsTech, they must punchout into a session. If there are no quoted items from PartsTech in the repair order, then creating a new punchout session is the way to go. If there are quoted items from a previous session in the repair order, then you can either create a new punchout session, or get the URL of an existing punchout session associated with items not yet ordered. The sessionId can be found in the API response when creating a new punchout session, along with the redirectUrl that will open the PartsTech session. 

Getting the URL of a previous punchout session continues to use the same sessionId that the URL is associated with. When opened, this not only lets users add items to the cart, it also allows users to modify the existing items in the cart too. In this case, when the cart data is received by your application, be aware that the existing items in the cart may have been removed or the quantity changed during the punchout session. Some cart information associated with each item may have been changed as well, like delivery method or shipping price. Those items and their associated data displayed in the repair order will need to be updated accordingly.

7. Vehicle information is sent when creating a punchout session to PartsTech search

When creating a new punchout session to the PartsTech search page, include vehicle information in the API request. Including vehicle information to identify a specific vehicle will automatically fill in the vehicle selection for your users when they load the PartsTech search page. The accepted vehicle parameters are listed in the Create Quote method documentation. There may not be vehicle information to include in every case, but when it is available then it should be included in the request to create a punchout session. If you decide to implement a punchout to our Stock Ordering page, vehicle information is not applicable in that case.

8. Repair Order number is sent when creating a punchout session to PartsTech search

Include the repair order number in the poNumber field when sending a request to the Create Quote method. Doing so will automatically fill in the PO text field in the PartsTech cart. Typically, users will enter the associated repair order number into the PO text field, if it is not included in the request. Sending the repair order number saves users’ time. This also enables our API to include the provided poNumber in the quote and order data for the session.

If the poNumber field is empty or null when creating a punchout session, this may result in orders being placed from our site with an empty PO text field. When a user places an order on our site and the PO text field is empty, the orderId is put into the poNumber field when the order request is sent to suppliers. Suppliers typically require a purchase order number in order API requests, so a value must be included in the poNumber field when our API sends suppliers an order request. This can lead to frustration for users when the order is delivered. In these cases, the purchase order number on the invoice would be the PartsTech orderId, which would look like a "random number" to users. It would be difficult for users to match the delivered items to the correct repair order. So include the repair order number in the poNumber field and save your users some time and frustration in their busy day!

9. Core charge can be displayed on the repair order

For parts that include Core charges, such as vehicle batteries, be able to display the Core charge on the repair order. Users usually do not need Core charges added to the cost and price of the repair order, but there are times when they do. Both of these cases should be handled in your application. We recommend labeling a part as having a Core charge and displaying the value of the Core charge in a way that it is not included in the total cost or price of the repair order. For cases where Core charges should be included in the repair order, we recommend allowing users to add the Core charge to the total cost and price of the repair order. Another path is to give users an option to add the Core charge to the repair order when the part is transferred from PartsTech to your application.

10. The minimum required Part fields are displayed in a repair order

There is a lot of data that is included in the part information our API provides in quote and order data. Based on our research and interviews with users, we require only the most important and valuable part data for shops to be able to see in their repair orders. The following data must be able to be displayed in repair orders:

• Part Name

• Part Number

• Quantity

• Cost

• Shipping Price

The vast majority of part orders will not have a shipping price. When they do, it is important to include any shipping price in the repair order, so the user knows the total cost of the order.

11. Tires are recognized separately from Parts and Tire specific fields are displayed in a repair order

An easy way to determine whether an item is a Tire from our API quote or order data is to check the partTypeName or partTypeId fields. In both our quote and order data, you can find these fields in the taxonomy object of each item in the parts list at orders.parts.taxonomy. You can check the partTypeName for the value, “Tire”. Or you could check the partTypeId for the value, 7636. Checking these fields for tire values will allow your application to know when to mark an item as a tire, and then display the appropriate tire fields.

12. The minimum required Tire fields are displayed in a repair order

Just like with our part data, there is a lot of tire information that our API provides in quote and order data. Based on our research and interviews with users, we require only the most important and valuable tire data for shops to be able to see in their repair orders. The following data must be able to be displayed in repair orders:

• Part Name

• Part Number

• Quantity

• Cost

• Shipping Price

• Size

• Federal Excise Tax (FET)

As you can see, there is overlap with required part fields. Shipping price is more common to see with tires than parts. The two tire specific fields that also must be displayed are Size and FET. Size will always be passed with tire data. FET only applies to a subset of tires, but when it is included in tire data your application receives from our API, then it should be displayed in the repair order.

13. The quantity of each quoted item can be modified within a repair order

When there are quoted items in a repair order, the quantity of each item should be editable within the repair order. When users change the quantity of items in a repair order, the quantity should be updated using our Update Cart method. The sessionId and a list (named updates) of orderItemId and quantity should be sent in the request. The response will include the updated list of items, and each item’s updated quantity. Be aware that changing the quantity of items may change the shipping price. This can be checked in the updated cart data returned from the Update Cart method. If the shipping price changes, the shipping price in the repair order should be updated accordingly.

IMPORTANT NOTE: Any items in the cart of the provided sessionId that are not included in the updates list of the Update Cart API request will be removed from the cart of that session.

14. Items in a repair order can be removed from the repair order

Quoted items in a repair order should be able to be removed from the repair order without punching out to PartsTech. When an item is removed from a repair order, the Remove Parts method should be used to update the cart of the provided sessionId. The orderItemId of each removed item should be included in the list of removals in the request. The response will include the updated list of items in the cart of the session.

15. The availability of cart items is checked before placing an order

If users will be able to place orders through PartsTech’s API within your application, then your application must check the availability of cart items before submitting the order request. You can check the availability of all the items in a single session by sessionId with the Check Cart Availability method. You can check the availability of individual items from one session or multiple sessions by orderItemId with the Check Custom Cart Availability method. The API response for both will include the most recent pricing and availability of those items directly from the suppliers. 

If there are any items that are not available for purchasing, the HTTP status code 402 will be returned. The response body will include the items that are not available, supplier information for each item not available, and an error message. Your application should handle this error gracefully. An error message should be displayed that clearly explains that some items are currently not available for ordering. The names of the currently unavailable items could also be displayed in the error message to the user. Doing so would allow them to know which items are available, so they can place an order with the available items.

16. The Purchase Order number is included in the order request

Include the purchase order number in the poNumber field when placing an order through the PartsTech API. If the purchase order number is not included, this may lead to some frustration for users when the order is delivered. There may be cases where the purchase order number on the invoice may not match to the repair order that the items were associated with. It would be difficult for users to match the delivered items to the correct repair order. So include the poNumber in the order request and save your users some time and frustration in their busy day!

17. Items in a repair order can be ordered in any combination

If users will be able to place orders through PartsTech’s API within your application, then your application must allow any single item or combination of items together to be ordered in a repair order. There could be any number of items in a repair order. Those items could all be from one PartsTech session or the items could be from multiple PartsTech sessions, depending on the workflow you decide to implement. This means that it’s not always as simple as submitting orders by the sessionId returned when creating a new punchout session. Users will want to order a subset of items from a session. They will also want to order items across multiple sessions. Our API has methods to handle any of these situations.

When users place an order for all of the items from a session, check the availability of the items by the sessionId. If all of the items are available, then place the order by the sessionId using the Submit Cart method (make sure to include the purchase order number in the poNumber field). If some of the session items are not available when checking availability and the user wants to order the available session items, then the available session items will need to be ordered together using the orderItemId of each item. We’ll cover this next.

There are methods that allow the ordering of items separately from their associated sessionId. These methods allow users to order items together in any combination they desire. In this workflow orderItemId, quantity, and storeId will be needed in the API requests. All three fields are in each order object that can be found in the cart data returned on cart callback and get cart. Orders are separated by store, so each order object contains a storeId, and one or more order items can be associated with each storeId. The storeId can be found for each order in the orders.store object, and orderItemId and its quantity can be found for each item in the orders.parts object. For this workflow, check the availability of the items by each orderItemId and its associated quantity. Now the available items can be ordered using the Order Custom Cart method. For the request in this method, each storeId and its associated orderItems are needed. As mentioned in previous sections, the purchase order number should be included in the order request in the poNumber field.

18. A test account for your application is provided to PartsTech

It is important that our teams have access to a test or demo account for your application. This empowers our Support and Sales teams to better help your customers get up and running with the PartsTech integration. It also allows us to create help documentation on our side specific to our partnership.