Embedded Files
Introduction
Introduction
Integrating your application with PartsTech using the Punchout API streamlines part and tire procurement. This REST API lets users open PartsTech from your application to search for items from their suppliers, add them to their cart, quote or order them, and send the quote or order data to your app. Quoted items can be easily ordered directly from your app without opening PartsTech. This guide will help developers understand the punchout workflow, endpoints, and how to start building a punchout integration.
Prerequisites
Prerequisites
For this integration you will need:
Development Partner credentials
Partner ID
Partner API Key
Development User account (with demo part and tire suppliers)
User ID (Username)
User API Key
An API endpoint to accept callbacks
The Partner and User development credentials are provided to new API partners during the on-boarding process. Contact Jake Benson at jbenson@partstech.com to get started if you are interested in an integration with PartsTech.
User Setup
User Setup
Before using the PartsTech integration in your application, users must create a PartsTech account, connect their supplier wholesale accounts in PartsTech, and enter their PartsTech user credentials (Username and API Key) into a form in your application. Save these credentials and associate them with the user in your system for authentication. Once setup is complete, users can begin using the integration.
Overview
Overview
This overview gives a high-level view of the punchout workflow from beginning to end assuming your PartsTech integration is complete and the user has completed the set up steps.
To start the punchout workflow, the user clicks the PartsTech punchout button in your app, triggering two calls to the PartsTech API:
Authentication endpoint: Verifies the user and partner, and returns a token to access subsequent endpoints.
Create session endpoint: Generates a unique session for the user and accepts a callback URL where PartsTech will send the session quote or order data. The two fields returned are the session ID that identifies the punchout session and the session URL.
2. Your app sends the user to the session URL in a new tab.
3. After adding items to the cart in PartsTech, the user has two options:
Order the items by clicking the Buy Now button. This sends orders to suppliers and the order data to your app's callback URL, closing the PartsTech tab and ending the punchout workflow.
Transfer a quote for the items by clicking the Submit Quote button. This sends quote data to your app's callback URL, closing the PartsTech tab. The user can then order the quoted items in your app without returning to PartsTech.
Let’s continue with the user clicking Submit Quote to transfer the quoted items to your app.
Authentication endpoint: Get a token for the next two calls.
Check availability endpoint: Gets up to date pricing and availability directly from the suppliers for the quoted items.
Place orders endpoint: Sends the orders to the appropriate suppliers.
Next let’s dig deeper into each step of the workflow.
Authentication and Access
Authentication and Access
Endpoint URL: https://api.partstech.com/oauth/access
Endpoint Reference: https://api-docs.partstech.com/#operation/getAcessToken
To access PartsTech API endpoints, you need to use OAuth with JSON Web Tokens. To get an access token, use the /oauth/access endpoint, which requires Partner and User credentials in a POST request. Access tokens expire after 60 minutes and must be included in the request header for each subsequent API call.
Authorization header format:
Authorization: Bearer accessToken
Example Request
{
"accessType":"user",
"credentials":{
"partner":{
"id":"your_partnerId",
"key":"8c9c4d17864e44e39a8756341b1cf448"
},
"user":{
"id":"your_test_userId",
"key":"f850ea4d68bf4eb7962a8cfc1e2b1a1d"
}
}
}
The accessType must be "user" for punchout endpoints. Use your Partner credentials for every authentication request your app sends. Each user has a unique User Id and API Key to be saved in your app. Use their credentials when the user wants to punchout or place an order. Development Partner credentials can be used with your test User account. After your integration is approved to start onboarding users you will be provided Partner credentials to be used with real User accounts.
After sending valid credentials, the API returns an accessToken which will be used in the authorization header of subsequent API requests for the specified user.
Example Response
{
"tokenType":"bearer",
"accessToken":"ecJ2eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhcHAucGFydHN0ZWNoLmNvbSIsInBhcnRuZXIiOiJzaG9wbW9ua2V5IiwiZXhwIjoxNjgzODI5OTc1LCJ1c2VyIjoiZGVtb19oZWxlbiIsInNob3AiOjg3fQ.QrdCizKXRAZe-wU0rQbZjtUy50FhgQtbODn0UFjEc48",
"refreshToken":"ecJ4eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhcHAucGFydHN0ZWNoLmNvbSIsInBhcnRuZXIiOiJzaG9wbW9ua2V5IiwiZXhwIjoxNjgzODI5OTc1LCJ1c2VyIjoiZGVtb19oZWxlbiIsInNob3AiOjg3LCJzdWIiOiJyZWZyZXNoIn0.2coxkRG5gdCWMZ34C80CA7YrJuRrtDB-kPbzUldw2rI",
"expiresIn":3600,
"partner":"your_partnerId",
"username":"your_test_userId"
}
Create Session
Create Session
Endpoint URL: https://api.partstech.com/punchout/quote/create
Endpoint Reference: https://api-docs.partstech.com/#operation/createQuote
Use the /punchout/quote/create endpoint with a POST request to create a new punchout session. The returned redirectURL is the session URL where your app will send the user to procure parts and tires in a new tab. Sessions expire after 120 days for platform performance and stability.
Example Request
{
"searchParams":{
"vin":"1FMZU74E2YZA89633"
},
"urls":{
"callbackUrl":"https://your.callback.url.com/return-cart",
"callbackOrderUrl":"https://your.callback.url.com/return-cart"
},
"settings":{
"poNumber":"123"
}
}
You can include vehicle identifiers and search parameters in your request. A vehicle identifier will let PartsTech automatically select the vehicle in that session, while a search parameter will trigger an automatic search when the user is sent to the session.
There are four vehicle identifiers that can be used:
VIN
Plate & State
PartsTech Vehicle ID
Year, Make, Model, Submodel, Engine
The following search parameters can be used:
Part Number
Part Type ID
Keyword
Tire Size
Part Type ID and Keyword parameters require a vehicle identifier to be included in the request. Part Number and Tire Size parameters can be sent with or without a vehicle identifier. If your application knows the vehicle that a user needs parts for, always include its identifier in the request to create a session.
In the request, URLs can be included that impact the behavior of the PartsTech cart buttons:
callbackUrl: The URL to receive quote data when the user clicks Submit Quote. If not included, the Submit Quote button will be removed from the cart.
callbackOrderUrl: The URL to receive order data when the user clicks Buy Now. If not included, the Buy Now button will be removed from the cart.
returnUrl: The URL loaded after a cart button is clicked.
It is important to automatically close the PartsTech tab after a cart button is clicked. A listener/watcher on the cart buttons can be used to automatically close the PartsTech tab when a cart button is clicked. Alternatively, a returnUrl of a page that closes the tab on load can be included in the request, but it's less efficient.
To automatically populate the PO field in the PartsTech cart, include a Purchase Order number in the poNumber field. This is typically the work order number at this point in the workflow. If the PO field is empty and the Buy Now button is used, the PartsTech generated orderId will be sent to suppliers as the PO number, making it difficult for users to match delivered items to the correct work order.
Example Response
{
"sessionId":"1ag3d2b5240e4jcbbe3ee9c49c929fe4",
"redirectUrl":"https://app.partstech.com/api-search/your_partnerId/your_test_userId/1ag3d2b5240e4jcbbe3ee9c49c929fe4/"
}
The API response when creating a session includes two fields:
sessionId: A unique identifier for the session that can be used to link callback data to the correct user and work order.
redirectUrl: A URL for the PartsTech search page customized with provided vehicle information, search parameters, callback URLs, and PO number. Only send users to sessions created for them, as the redirectUrl logs them into the corresponding user's account.
Cart Callback
Cart Callback
Endpoint Reference: https://api-docs.partstech.com/#tag/callback-cart/paths/~1our-callback/post
The Cart Callback allows PartsTech to send session quote and order data to your application. Quote data is sent when the Submit Quote button is used, while order data is sent when the Buy Now button is used. To receive these callbacks, you need to set up an endpoint that can accept POST requests from PartsTech.
The URL of your callback endpoint will be the callbackUrl and callbackOrderUrl in the create session request. Your endpoint should be able to differentiate between quote and order data when a session's callback data is received. This can be done by using the action field described below.
Example Callback Request (with one quoted part and one quoted tire)
{
"user":{
"username":"your_test_userId",
"email":"your_test_userId@mailinator.com",
"enabled":true,
"lastLogin":"2023-05-12T14:54:46Z",
"registrationDate":null,
"allowOrderEmails":true,
"firstName":"Test",
"lastName":"User",
"timeZone":"America\/New_York",
"demo":true
},
"sessionId":"1ag3d2b5240e4jcbbe3ee9c49c929fe4",
"orders":[
{
"tax":0.0,
"totalPrice":24.99,
"discount":0.0,
"coreCharge":0.0,
"fet":0.0,
"shippingPrice":0.0,
"paymentType":"Wholesale",
"poNumber":"123",
"supplier":{
"allowStoreSelect":false,
"availabilitySelect":false,
"id":16473,
"name":"O'Reilly TEST"
},
"store":{
"id":213133,
"name":"O'Reilly TEST STORE",
"address":{
"address1":"One Broadway",
"city":"CAMBRIDGE",
"state":"MA",
"zipCode":"02142-1100",
"country":"US"
}
},
"delivery":{
"name":"hotshot",
"price":0.0
},
"buyerShop":{
"address1":"12 High Street",
"city":"BOSTON",
"state":"MA",
"zipCode":"02110",
"country":"US"
},
"parts":[
{
"orderItemId":"61cc6d56932f4bfd8425427ff2d54a80",
"partId":"BDCS-49750",
"lineCardId":365421,
"quantity":1,
"price":{
"list":42.36,
"price":24.99,
"cost":24.99,
"core":0.0,
"fet":0.0,
"retail":49.98
},
"partName":"Wix Air Filter",
"partNumber":"49750",
"imageUrl":"https:\/\/image.partstech.com\/IK9O-fKaw_-G_lKskMaqCEjCuNffPeXMCBqZYzYQqUQ\/rs:fit:110:110:0\/g:sm\/czM6Ly9wYXJ0c3RlY2gtaW1hZ2Utc2VydmVyL2ltYWdlcy80NS80OS80YS80NTQ5NGE5MDZhYmU2YzMyZDE3M2MwN2QxMzMyMTMxMWNlNDlmY2U0LnBuZw",
"partstechCatalogURL":"https:\/\/app.partstech.com\/product\/BDCS-49750?part_term=6192&supplierId=16473&credentialId=210414&linecard=365421&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"BDCS",
"brandName":"Wix",
"id":917,
"displayName":"Wix"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":6192,
"partTypeName":"Air Filter",
"partTypeDescription":"An air filter for the air intake system of a vehicle's engine.",
"categoryId":12,
"categoryName":"Air and Fuel Delivery",
"subCategoryId":153,
"subCategoryName":"Filters"
},
"partCategory":"Maintenance",
"storesAvailability":[
{
"specificName":"BUFFALO MO 4047 - STR",
"quantity":1,
"main":true
}
],
"attributes":[
{
"name":"Qty",
"label":"Quantity per vehicle",
"value":"1",
"type":"Both"
}
],
"deliveryNotes":[
]
}
]
},
{
"tax":0.0,
"totalPrice":451.96,
"discount":0.0,
"coreCharge":0.0,
"fet":0.0,
"shippingPrice":0.0,
"paymentType":"Wholesale",
"poNumber":"123",
"supplier":{
"allowStoreSelect":false,
"availabilitySelect":false,
"id":16645,
"name":"TireHub - Direct"
},
"store":{
"id":233545,
"name":"TireHub Location",
"address":{
"address1":"1 Broadway",
"city":"Cambridge",
"state":"MA",
"zipCode":"02142-1100",
"country":"US"
}
},
"delivery":{
"name":"delivery",
"price":0.0
},
"buyerShop":{
"address1":"12 High Street",
"city":"BOSTON",
"state":"MA",
"zipCode":"02110",
"country":"US"
},
"parts":[
{
"orderItemId":"54982ba182e240ce8739be119a7386ae",
"partId":"DVFB-407780374",
"lineCardId":461640,
"quantity":4,
"price":{
"list":180.78,
"price":112.99,
"cost":112.99,
"core":0.0,
"fet":null,
"retail":180.78
},
"partName":"GOODYEAR Assurance All-Season",
"partNumber":"407780374",
"imageUrl":"https:\/\/image.partstech.com\/gL9lhBwrvPHXD0lbexsZZaZ_8HanelvusXbxijANsPU\/rs:fit:110:110:0\/g:sm\/aHR0cHM6Ly9tZWRpYS50aXJlbGlicmFyeS5jb20vaW1hZ2VzLzIyMWU2ZDY5NDM3MzQ3ZWM4ODQ2NmRhOWY1MjAyNjg2",
"partstechCatalogURL":"https:\/\/app.partstech.com\/product\/DVFB-407780374?part_term=7636&supplierId=16645&credentialId=259425&linecard=461640&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"DVFB",
"brandName":"Goodyear",
"id":4786,
"displayName":"Goodyear"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":7636,
"partTypeName":"Tire",
"partTypeDescription":"Tire.",
"categoryId":17,
"categoryName":"Tire and Wheel",
"subCategoryId":214,
"subCategoryName":"Tire"
},
"partCategory":"Service",
"tireSize":"205\/65R16 95H",
"storesAvailability":[
{
"specificName":"TLC 144 MOORESTOWN",
"quantity":18,
"main":true
},
{
"specificName":"TLC 102 WEST DEPTFORD",
"quantity":64,
"main":false
},
{
"specificName":"TLC 145 ALLENTOWN",
"quantity":253,
"main":false
},
{
"specificName":"TLC 149 GREENSBORO",
"quantity":250,
"main":false
},
{
"specificName":"TLC 222 SHREVEPORT",
"quantity":301,
"main":false
}
],
"attributes":[
{
"name":"TiresRunFlat",
"label":"Run-flat",
"value":"Not Run-flat",
"type":"Part"
},
{
"name":"TiresMileageRating",
"label":"Warranty",
"value":"65000 miles",
"type":"Part"
},
{
"name":"TiresSize",
"label":"Size",
"value":"205\/65R16 95H",
"type":"Part"
},
{
"name":"TiresCategoryLabel",
"label":"Category",
"value":"All Season",
"type":"Part"
},
{
"name":"TiresLoadIndex",
"label":"Load Index",
"value":"95",
"type":"Part"
},
{
"name":"TiresSpeedRating",
"label":"Speed Rating",
"value":"H",
"type":"Part"
},
{
"name":"TiresLoadRange",
"label":"Load Range",
"value":"SL",
"type":"Part"
},
{
"name":"TiresSideWallStyle",
"label":"Side Wall Style",
"value":"Blackwall",
"type":"Part"
},
{
"name":"TiresQuality",
"label":"UTQG",
"value":"600 A B",
"type":"Part"
}
],
"deliveryNotes":[
{
"label":"Order By",
"text":"9:55 AM"
},
{
"label":"Delivery By",
"text":"6:00 PM Tomorrow"
}
]
}
]
}
],
"action":"SUBMIT_QUOTE"
}
The cart callback request contains the following key information:
Top-level fields:
user: User information of the authenticated session.
sessionId: A unique identifier for the session that can be used to link callback data to the correct user and work order.
orders: Contains quote or order information, including supplier, pricing, and detailed part/tire information.
action: Indicates whether the callback contains quote or order data. Value "SUBMIT_QUOTE" indicates quote data, and "PURCHASE" indicates order data.
Quote and order data:
The schema for quote and order data is almost the same, the difference being that order data has two additional fields: id (PartsTech generated order ID) and orderUrl (URL for order details).
Each order in the orders list includes a supplier, a store (supplier location), and a list of items quoted from that store. Orders are separated by store. Suppliers and stores have unique IDs found in the supplier and store of each order.
The parts list within each order contains detailed part and pricing information for each item. Each item in a cart is assigned a unique orderItemId that references the exact item, its quote information, and order options such as shipping method, supplier notes, and PO number. You will use the orderItemId to specify each item in requests to check availability and place orders.
Check Availability
Check Availability
Endpoint URL: https://api.partstech.com/punchout/cart/custom/availability
Endpoint Reference: https://api-docs.partstech.com/#operation/checkItemsAvailability
The /punchout/cart/custom/availability endpoint provides real-time pricing and availability information directly from suppliers. Pricing and availability can change from the time an item is quoted, to the time it is ordered. This endpoint should be used before attempting to place an order, so users can be notified of any price changes or unavailable items.
Please note that while the PartsTech API is optimized to deliver quick responses, this endpoint depends on the response times of suppliers' APIs, which may vary.
To use this endpoint, make a POST request with a list of items including their respective orderItemId and desired quantity. Each item can have a maximum requested quantity of 99.
Example Request
{
"orderItems":[
{
"orderItemId":"2cdd9e30cf354e9ca680e13d04f535e6",
"quantity":1
},
{
"orderItemId":"b1677eb854854f9abb64f54f66c21f59",
"quantity":4
}
]
}
Example Response
{
"user":{
"username":"your_test_userId",
"email":"your_test_userId@mailinator.com",
"enabled":true,
"lastLogin":"2023-05-12T14:54:46Z",
"registrationDate":null,
"allowOrderEmails":true,
"firstName":"Test",
"lastName":"User",
"timeZone":"America\/New_York",
"demo":true
},
"sessionId":"1ag3d2b5240e4jcbbe3ee9c49c929fe4",
"orders":[
{
"tax":0.0,
"totalPrice":24.99,
"discount":0.0,
"coreCharge":0.0,
"fet":0.0,
"shippingPrice":0.0,
"paymentType":"Wholesale",
"poNumber":"123",
"supplier":{
"allowStoreSelect":false,
"availabilitySelect":false,
"id":16473,
"name":"O'Reilly TEST"
},
"store":{
"id":213133,
"name":"O'Reilly TEST STORE",
"address":{
"address1":"One Broadway",
"city":"CAMBRIDGE",
"state":"MA",
"zipCode":"02142-1100",
"country":"US"
}
},
"delivery":{
"name":"hotshot",
"price":0.0
},
"buyerShop":{
"address1":"12 High Street",
"city":"BOSTON",
"state":"MA",
"zipCode":"02110",
"country":"US"
},
"parts":[
{
"orderItemId":"2cdd9e30cf354e9ca680e13d04f535e6",
"partId":"BDCS-49750",
"lineCardId":365421,
"quantity":1,
"price":{
"list":42.36,
"price":24.99,
"cost":24.99,
"core":0.0,
"fet":0.0,
"retail":49.98
},
"partName":"Wix Air Filter",
"partNumber":"49750",
"imageUrl":"https:\/\/image.partstech.com\/IK9O-fKaw_-G_lKskMaqCEjCuNffPeXMCBqZYzYQqUQ\/rs:fit:110:110:0\/g:sm\/czM6Ly9wYXJ0c3RlY2gtaW1hZ2Utc2VydmVyL2ltYWdlcy80NS80OS80YS80NTQ5NGE5MDZhYmU2YzMyZDE3M2MwN2QxMzMyMTMxMWNlNDlmY2U0LnBuZw",
"partstechCatalogURL":"https:\/\/app.partstech.com\/product\/BDCS-49750?part_term=6192&supplierId=16473&credentialId=210414&linecard=365421&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"BDCS",
"brandName":"Wix",
"id":917,
"displayName":"Wix"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":6192,
"partTypeName":"Air Filter",
"partTypeDescription":"An air filter for the air intake system of a vehicle's engine.",
"categoryId":12,
"categoryName":"Air and Fuel Delivery",
"subCategoryId":153,
"subCategoryName":"Filters"
},
"partCategory":"Maintenance",
"storesAvailability":[
{
"specificName":"BUFFALO MO 4047 - STR",
"quantity":1,
"main":true
}
],
"attributes":[
{
"name":"Qty",
"label":"Quantity per vehicle",
"value":"1",
"type":"Both"
}
],
"deliveryNotes":[
]
}
]
},
{
"tax":0.0,
"totalPrice":451.96,
"discount":0.0,
"coreCharge":0.0,
"fet":0.0,
"shippingPrice":0.0,
"paymentType":"Wholesale",
"poNumber":"123",
"supplier":{
"allowStoreSelect":false,
"availabilitySelect":false,
"id":16645,
"name":"TireHub - Direct"
},
"store":{
"id":233545,
"name":"TireHub Location",
"address":{
"address1":"1 Broadway",
"city":"Cambridge",
"state":"MA",
"zipCode":"02142-1100",
"country":"US"
}
},
"delivery":{
"name":"delivery",
"price":0.0
},
"buyerShop":{
"address1":"12 High Street",
"city":"BOSTON",
"state":"MA",
"zipCode":"02110",
"country":"US"
},
"parts":[
{
"orderItemId":"b1677eb854854f9abb64f54f66c21f59",
"partId":"DVFB-407780374",
"lineCardId":461640,
"quantity":4,
"price":{
"list":180.78,
"price":112.99,
"cost":112.99,
"core":0.0,
"fet":null,
"retail":180.78
},
"partName":"GOODYEAR Assurance All-Season",
"partNumber":"407780374",
"imageUrl":"https:\/\/image.partstech.com\/gL9lhBwrvPHXD0lbexsZZaZ_8HanelvusXbxijANsPU\/rs:fit:110:110:0\/g:sm\/aHR0cHM6Ly9tZWRpYS50aXJlbGlicmFyeS5jb20vaW1hZ2VzLzIyMWU2ZDY5NDM3MzQ3ZWM4ODQ2NmRhOWY1MjAyNjg2",
"partstechCatalogURL":"https:\/\/app.partstech.com\/product\/DVFB-407780374?part_term=7636&supplierId=16645&credentialId=259425&linecard=461640&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"DVFB",
"brandName":"Goodyear",
"id":4786,
"displayName":"Goodyear"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":7636,
"partTypeName":"Tire",
"partTypeDescription":"Tire.",
"categoryId":17,
"categoryName":"Tire and Wheel",
"subCategoryId":214,
"subCategoryName":"Tire"
},
"partCategory":"Service",
"tireSize":"205\/65R16 95H",
"storesAvailability":[
{
"specificName":"TLC 144 MOORESTOWN",
"quantity":7,
"main":true
},
{
"specificName":"TLC 118 NORTH JERSEY",
"quantity":109,
"main":false
},
{
"specificName":"TLC 135 LONG ISLAND",
"quantity":125,
"main":false
},
{
"specificName":"TLC 145 ALLENTOWN",
"quantity":253,
"main":false
},
{
"specificName":"TLC 115 HARTFORD",
"quantity":18,
"main":false
},
{
"specificName":"TLC 101 BALTIMORE",
"quantity":52,
"main":false
},
{
"specificName":"TLC 142 ALBANY",
"quantity":24,
"main":false
},
{
"specificName":"TLC 218 WASHINGTON DC",
"quantity":16,
"main":false
},
{
"specificName":"TLC 102 WEST DEPTFORD",
"quantity":54,
"main":false
},
{
"specificName":"TLC 122 RICHMOND",
"quantity":23,
"main":false
},
{
"specificName":"TLC 213 SUFFOLK",
"quantity":18,
"main":false
},
{
"specificName":"TLC 127 PITTSBURGH",
"quantity":65,
"main":false
},
{
"specificName":"TLC 116 CLEVELAND",
"quantity":22,
"main":false
},
{
"specificName":"TLC 149 GREENSBORO",
"quantity":246,
"main":false
},
{
"specificName":"TLC 124 JACKSON",
"quantity":186,
"main":false
},
{
"specificName":"TLC 222 SHREVEPORT",
"quantity":301,
"main":false
}
],
"attributes":[
{
"name":"TiresRunFlat",
"label":"Run-flat",
"value":"Not Run-flat",
"type":"Part"
},
{
"name":"TiresMileageRating",
"label":"Warranty",
"value":"65000 miles",
"type":"Part"
},
{
"name":"TiresSize",
"label":"Size",
"value":"205\/65R16 95H",
"type":"Part"
},
{
"name":"TiresCategoryLabel",
"label":"Category",
"value":"All Season",
"type":"Part"
},
{
"name":"TiresLoadIndex",
"label":"Load Index",
"value":"95",
"type":"Part"
},
{
"name":"TiresSpeedRating",
"label":"Speed Rating",
"value":"H",
"type":"Part"
},
{
"name":"TiresLoadRange",
"label":"Load Range",
"value":"SL",
"type":"Part"
},
{
"name":"TiresSideWallStyle",
"label":"Side Wall Style",
"value":"Blackwall",
"type":"Part"
},
{
"name":"TiresQuality",
"label":"UTQG",
"value":"600 A B",
"type":"Part"
}
],
"deliveryNotes":[
{
"label":"Order By",
"text":"7:00 AM"
},
{
"label":"Delivery By",
"text":"1:00 PM Tomorrow"
}
]
}
]
}
],
"action":"SUBMIT_QUOTE"
}
If all items are available in the requested quantities, a successful response with a 200 HTTP status code will be returned. The response will include a list of orders with the current cost of each item. Make sure to check other pricing fields for any changes that would affect the total cost, such as shippingPrice or fet (if applicable).
If there are pricing changes, update the necessary values in the work order and inform the user about the changes. The user can decide whether to proceed with the order at the updated total cost or cancel it.
Example 402 Unavailable Item Error Response
{
"error":{
"code":"OrderAvailabilityError",
"message":"Some orders are not available for purchasing"
},
"errorDetails":[
{
"supplier":{
"id":16473,
"name":"O'Reilly TEST"
},
"store":{
"id":213133,
"name":"O'Reilly TEST STORE"
},
"errors":[
"Invalid shipping method"
],
"parts":[
{
"orderItemId":"2cdd9e30cf354e9ca680e13d04f535e6",
"partId":"BDCS-49750",
"quantity":99,
"errors":[
"Only 81 left in stock"
]
}
]
}
]
}
When one or more items are unavailable for ordering, a response with a 402 HTTP status code will be returned. The response will contain details about the availability error, including which items were unavailable and errors fields specifying the reason for each item.
In such cases, inform the user about the unavailable items and let them decide on the next steps. They may choose to proceed with ordering the available items and return later for the currently unavailable ones when they become available. Alternatively, they can punchout to PartsTech to explore alternative items that are currently available for immediate ordering.
Place Orders
Place Orders
Endpoint URL: https://api.partstech.com/punchout/cart/custom/order
Endpoint Reference: https://api-docs.partstech.com/#operation/submitItems
The /punchout/cart/custom/order endpoint is used to place orders for quoted items. Quoted items from different sessions can be included in a single request. Each order in the request is associated with a specific store and requires a storeId. An order must include a list of items with their respective orderItemId and requested quantity. Each orderItemId can only be used once and the maximum accepted quantity per item is 99. Any one order in the request cannot contain two or more orderItemIds of the same item. For this case, simply use one of the orderItemIds for the item and set the corresponding quantity to the correct value.
Example Request
{
"orders":[
{
"storeId":213133,
"orderItems":[
{
"orderItemId":"893e6164c883404898400772836bc6f7",
"quantity":2
},
{
"orderItemId":"6b05ab97e308434d9810d5b6b180a388",
"quantity":1
}
]
},
{
"storeId":233545,
"orderItems":[
{
"orderItemId":"36a4cfa8d09e40a8bd5ed510f078176d",
"quantity":4
}
]
}
]
}
It is optional to include notes and a poNumber in each order. If provided, they will overwrite any supplier notes or PO number entered in PartsTech for that store's order. If these fields are omitted, PartsTech will use the supplier notes or PO number from the cart. Any supplier notes and PO numbers from the cart are sent in the cart callback data to your application.
It is important to provide a poNumber to PartsTech for suppliers. While your application should send a poNumber when creating a session, users can edit the cart's PO field. If there is no poNumber in the cart callback data for a store's quote, you should include a poNumber in that store's order request. Otherwise, PartsTech will use the PartsTech generated orderId as the PO number, making it difficult for users to match delivered parts to the correct work order.
The response includes a list of orders sent to suppliers. It is in the same schema as order data in the cart callback.
Example Response
{
"orders":[
{
"id":48297402,
"tax":0,
"totalPrice":58.97,
"discount":0,
"coreCharge":0,
"fet":0,
"shippingPrice":0,
"paymentType":"Wholesale",
"poNumber":"123",
"notes":"",
"orderUrl":"https://app.partstech.com/order/122/d249762eb63c4ee986bd24248ab987e1",
"supplier":{
"allowStoreSelect":false,
"availabilitySelect":false,
"id":16473,
"name":"O'Reilly TEST"
},
"store":{
"id":213133,
"name":"O'Reilly TEST STORE",
"address":{
"address1":"One Broadway",
"city":"CAMBRIDGE",
"state":"MA",
"zipCode":"02142-1100",
"country":"US"
},
"sellerId":"001"
},
"delivery":{
"name":"hotshot",
"price":0
},
"buyerShop":{
"address1":"12 High Street",
"city":"BOSTON",
"state":"MA",
"zipCode":"02110",
"country":"US"
},
"parts":[
{
"orderItemId":"893e6164c883404898400772836bc6f7",
"partId":"BBWQ-HP-1010",
"lineCardId":363617,
"quantity":2,
"price":{
"list":28.8,
"price":16.99,
"cost":16.99,
"core":0,
"fet":0,
"retail":116.99
},
"partName":"K&N Engine Oil Filter",
"partNumber":"HP1010",
"imageUrl":"https://image.partstech.com/fajBVpIOgJFJUQnolmfk46pbx5EfTvDehJGde3iYAIE/rs:fit:110:110:0/g:sm/czM6Ly9wYXJ0c3RlY2gtaW1hZ2Utc2VydmVyL2ltYWdlcy9jNS9kOC9jOC9jNWQ4Yzg1YWE1YjZlODgxOTBlYTk0M2ZhMGI0NWZlNTc1NzIwYTViLmpwZw",
"partstechCatalogURL":"https://app.partstech.com/product/BBWQ-HP-1010?part_term=5340&supplierId=16473&credentialId=210414&linecard=363617&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"BBWQ",
"brandName":"K&N",
"id":388,
"displayName":"K&N"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":5340,
"partTypeName":"Engine Oil Filter",
"partTypeDescription":"Please consider adding \"External\" position to this terminology name.",
"categoryId":71,
"categoryName":"Engine",
"subCategoryId":153,
"subCategoryName":"Filters"
},
"partCategory":"Maintenance",
"attributes":[
{
"name":"Qty",
"label":"Quantity per vehicle",
"value":"1",
"type":"Both"
},
{
"name":"WarrantySpecial",
"label":"Warranty Special",
"value":"1 Year Limited Warranty",
"type":"Part"
}
],
"deliveryNotes":[
]
},
{
"orderItemId":"6b05ab97e308434d9810d5b6b180a388",
"partId":"BDCS-49750",
"lineCardId":365421,
"quantity":1,
"price":{
"list":42.36,
"price":24.99,
"cost":24.99,
"core":0,
"fet":0,
"retail":49.98
},
"partName":"Wix Air Filter",
"partNumber":"49750",
"imageUrl":"https://image.partstech.com/IK9O-fKaw_-G_lKskMaqCEjCuNffPeXMCBqZYzYQqUQ/rs:fit:110:110:0/g:sm/czM6Ly9wYXJ0c3RlY2gtaW1hZ2Utc2VydmVyL2ltYWdlcy80NS80OS80YS80NTQ5NGE5MDZhYmU2YzMyZDE3M2MwN2QxMzMyMTMxMWNlNDlmY2U0LnBuZw",
"partstechCatalogURL":"https://app.partstech.com/product/BDCS-49750?part_term=6192&supplierId=16473&credentialId=210414&linecard=365421&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"BDCS",
"brandName":"Wix",
"id":917,
"displayName":"Wix"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":6192,
"partTypeName":"Air Filter",
"partTypeDescription":"An air filter for the air intake system of a vehicle's engine.",
"categoryId":12,
"categoryName":"Air and Fuel Delivery",
"subCategoryId":153,
"subCategoryName":"Filters"
},
"partCategory":"Maintenance",
"attributes":[
{
"name":"Qty",
"label":"Quantity per vehicle",
"value":"1",
"type":"Both"
}
],
"deliveryNotes":[
]
}
]
},
{
"id":48297401,
"tax":0,
"totalPrice":451.96,
"discount":0,
"coreCharge":0,
"fet":0,
"shippingPrice":0,
"paymentType":"Wholesale",
"poNumber":"123",
"notes":"",
"orderUrl":"https://app.partstech.com/order/122/eb83114ba581438d839f2e4bfdf4696b",
"supplier":{
"allowStoreSelect":false,
"availabilitySelect":false,
"id":16645,
"name":"TireHub - Direct"
},
"store":{
"id":233545,
"name":"TireHub Location",
"address":{
"address1":"1 Broadway",
"city":"Cambridge",
"state":"MA",
"zipCode":"02142-1100",
"country":"US"
},
"sellerId":null
},
"delivery":{
"name":"delivery",
"price":0
},
"buyerShop":{
"address1":"12 High Street",
"city":"BOSTON",
"state":"MA",
"zipCode":"02110",
"country":"US"
},
"parts":[
{
"orderItemId":"36a4cfa8d09e40a8bd5ed510f078176d",
"partId":"DVFB-407780374",
"lineCardId":461640,
"quantity":4,
"price":{
"list":180.78,
"price":112.99,
"cost":112.99,
"core":0,
"fet":null,
"retail":180.78
},
"partName":"GOODYEAR Assurance All-Season",
"partNumber":"407780374",
"imageUrl":"https://image.partstech.com/gL9lhBwrvPHXD0lbexsZZaZ_8HanelvusXbxijANsPU/rs:fit:110:110:0/g:sm/aHR0cHM6Ly9tZWRpYS50aXJlbGlicmFyeS5jb20vaW1hZ2VzLzIyMWU2ZDY5NDM3MzQ3ZWM4ODQ2NmRhOWY1MjAyNjg2",
"partstechCatalogURL":"https://app.partstech.com/product/DVFB-407780374?part_term=7636&supplierId=16645&credentialId=259425&linecard=461640&vehicle=607272",
"availability":true,
"backOrder":false,
"bundled":false,
"brand":{
"brandID":"DVFB",
"brandName":"Goodyear",
"id":4786,
"displayName":"Goodyear"
},
"vehicleId":607272,
"vehicleName":"2014 Honda Accord EX 2.4L L4 DOHC K24W1 i-VTEC",
"taxonomy":{
"partTypeId":7636,
"partTypeName":"Tire",
"partTypeDescription":"Tire.",
"categoryId":17,
"categoryName":"Tire and Wheel",
"subCategoryId":214,
"subCategoryName":"Tire"
},
"partCategory":"Service",
"tireSize":"205/65R16 95H",
"attributes":[
{
"name":"TiresRunFlat",
"label":"Run-flat",
"value":"Not Run-flat",
"type":"Part"
},
{
"name":"TiresMileageRating",
"label":"Warranty",
"value":"65000 miles",
"type":"Part"
},
{
"name":"TiresSize",
"label":"Size",
"value":"205/65R16 95H",
"type":"Part"
},
{
"name":"TiresCategoryLabel",
"label":"Category",
"value":"All Season",
"type":"Part"
},
{
"name":"TiresLoadIndex",
"label":"Load Index",
"value":"95",
"type":"Part"
},
{
"name":"TiresSpeedRating",
"label":"Speed Rating",
"value":"H",
"type":"Part"
},
{
"name":"TiresLoadRange",
"label":"Load Range",
"value":"SL",
"type":"Part"
},
{
"name":"TiresSideWallStyle",
"label":"Side Wall Style",
"value":"Blackwall",
"type":"Part"
},
{
"name":"TiresQuality",
"label":"UTQG",
"value":"600 A B",
"type":"Part"
}
],
"deliveryNotes":[
{
"label":"Order By",
"text":"7:00 AM"
},
{
"label":"Delivery By",
"text":"6:00 PM Wed, May 17"
}
]
}
]
}
]
}
Wrap Up
Wrap Up
Congratulations, you have reached the end of the guide! Throughout this guide, we have covered the key endpoints, concepts, and functionalities that will enable you to build a seamless PartsTech integration using the Punchout API. Let's recap what you have learned:
Authentication: We started by discussing how to access PartsTech’s API endpoints using JSON Web Tokens. You now know to provide Partner and User credentials to get an access token to use in the authorization header of subsequent requests.
Session Creation: You discovered how to create a session, including sending vehicle identifiers, search parameters, PO numbers, and callback URLs. By leveraging these fields effectively, you can streamline the user experience and enable automatic searches, selection of vehicles, and filling in the PO field.
Cart Callbacks: We explored the cart callback, which allows PartsTech's API to send quote and order data to your application. You learned how to handle the callback request, distinguishing between quote and order data using the action field. Additionally, we discussed the significance of the sessionId, redirectUrl, and the structure of the orders and parts lists.
Checking Availability: You now understand how to utilize the /punchout/cart/custom/availability endpoint to retrieve real-time pricing and availability information for requested items. We highlighted the importance of considering potential pricing changes and notifying users accordingly. In cases where items are unavailable, you learned how to handle the response and guide users in making informed decisions.
Placing Orders: The final step in the workflow is placing orders for quoted items using the /punchout/cart/custom/order endpoint. You gained insights into the required parameters, storeId, orderItemId, and quantity. We emphasized the significance of including a poNumber for users to easily match delivered parts to the correct work order.
By following this guide, you are now well-equipped to implement the PartsTech Punchout workflow in your application. Remember to refer to the API reference documentation for schema and data field details. To be sure that your integration will meet PartsTech’s minimum standard for a great user experience, check out the Punchout Integration Requirements.
We look forward to seeing the amazing integration you build and the value it brings to your users. If you have any further questions, please contact Alex Keller at akeller@partstech.com. Happy integrating!
Page updated
Report abuse