A complete integration guide for embedding Blackinton Product Configuration Services into your e-commerce or ERP platform — with full API reference, authentication, and setup instructions.
Embed into any modern e-commerce platform with full cart control
Works with any ERP or order management system
Unique 36-char GUIDs track every product configuration
Products, Orders, Design & Catalog endpoints included
Product Configuration Services (PCS) is a suite of technology solutions designed to simplify how Blackinton dealers sell customizable products online. Maintaining product offerings and delivering an intuitive, rules-compliant shopping experience can be complex — PCS removes that burden entirely.
PCS provides an IFRAME-integrated solution that delivers a complete, tailored browsing and configuration experience for Blackinton products — eliminating the need to build or maintain a local product library.
PCS is exclusively dedicated to Blackinton product customization. Dealers continue to manage non-Blackinton products and the overall checkout experience independently within their own platforms.
Before integrating PCS with a shopping cart platform, ensure the following capabilities are supported:
The cart system must support a dedicated product page layout that can host an IFRAME. The IFRAME src attribute will reference an external URL — e.g. https://build.blackinton.com — different from your shopping system's domain.
The cart system must allow custom JavaScript on the PCS page. PCS uses JavaScript's postMessage method to communicate between the IFRAME and the hosting page. External CDN references load the required JS files.
The cart system must support adding products programmatically — client-side or server-side — using a style number/identifier, typically via an API or HTTP POST.
The integration uses a single custom product — recommended style number: VHB-PCS. Each time a Blackinton product is configured via PCS, this product is added to the cart.
The cart accepts custom JSON stored with the product through the full order creation lifecycle.
Add a multi-line text option to the VHB-PCS product. PCS uses this to store and retrieve JSON as the product moves from cart to order.
Configuration HTML: Well-formed HTML snippets with CSS tags describing the product configuration.
Design Identifier: A 36-character GUID (design key) uniquely tracking each product configuration.
The ERP platform must support a custom page hosting an IFRAME via the src attribute pointing to a third-party domain, e.g. https://build.blackinton.com.
The ERP platform must allow CDN/external JavaScript links. PCS uses postMessage for cross-origin communication, sending JSON product configuration data from the IFRAME to the host page.
The ERP system must provide programmatic control to create sales orders, add items, and manage transactional elements via API to support automation workflows.
PCS POSTs JSON data in response to operations. The ERP system must persist this data — including Configuration HTML and Design Keys — as needed.
PCS delivers a responsive, intuitive experience by combining a custom product page/template, an HTML IFRAME element, and supporting JavaScript. A secure postMessage messaging system creates a safe communication pathway between your web application and the PCS IFRAME.
Users can browse the Blackinton catalog by category, search by style number or keywords, and configure products entirely within the embedded IFRAME. Dealer-specific injectable CSS enables custom branding.
When a product configuration is completed, PCS raises a JavaScript event in your hosting page. Two key events must be declared:
function pcs_ConfigurationCompleted(data) {
// Called when visitor clicks "Add to Cart" or "Update Cart"
// data = JSON object with configuration details including Design Key
}
function pcs_ConfigurationCancelled(data) {
// Called when visitor clicks "Cancel" or "Back"
// data = JSON object with configuration details
}A Design Key (DK) is a 36-character GUID that uniquely identifies a product configuration. Returned via pcs_ConfigurationCompleted — it must be saved persistently and is required for all future API order calls.
Blackinton stores configuration data only. Cart quantities and retail pricing are not stored. You must provide quantity and retail pricing via the API when placing an order.
The host page must include specific CSS, JavaScript, and the IFRAME element. A full-page width layout is strongly recommended.
The hosting page must have jQuery loaded. It may already be present in your cart environment, or can be added explicitly to just the PCS page.
Add the following to the <HEAD> section. Replace highlighted regions with your Tenant ID.
<script
src="//build.blackinton.com/api/YOUR-TENANT-ID/script/?filename=pcs-core.js"
type="text/javascript" crossorigin="anonymous"></script>
<link rel="stylesheet"
href="//build.blackinton.com/api/YOUR-TENANT-ID/css/?filename=pcs-core.css"
type="text/css" crossorigin="anonymous"/><link rel="stylesheet"
href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"
crossorigin="anonymous" referrerpolicy="no-referrer" /><div class="pcs-iframe-loader"></div>
<iframe id="pcs_iframe" name="pcs_iframe"
src="//build.blackinton.com/YOUR-TENANT-ID/catalog/"
class="pcs-iframe" scrolling="no" title="">
</iframe>| Parameter | Required | Description |
|---|---|---|
btn=XXXX | Optional | Custom text for the action button, e.g. "Add to Cart". Appears next to the QTY field. |
sl=true|false | Optional | Renders a "Save for Later" link. Default false. Fires pcs_ConfigurationCompleted when clicked. |
<div class="pcs-iframe-loader"></div>
<iframe id="pcs_iframe" name="pcs_iframe"
src="//build.blackinton.com/YOUR-TENANT-ID/product/?style=B38"
class="pcs-iframe" scrolling="no" title="">
</iframe>| Parameter | Required | Description |
|---|---|---|
style=XXXX | Optional | Valid Blackinton catalog style number, e.g. "B38". Loads that product directly. |
btn=XXXX | Optional | Custom button text, e.g. "Add to Cart", "Update Cart". |
dk=XXXX | Optional | Design Key — pass this when editing an existing configuration. |
qty=XXXX | Optional | Quantity — typically used together with a dk value. |
Never copy or store PCS supporting scripts statically. They are delivered dynamically per API call, are tenant-specific, and can change at any time without notice.
Orders with Draft (DR) status must be released to production manually via Web Wizard at https://app.blackinton.com or programmatically via the API. Daily email notifications summarize all pending PCS draft orders.
Blackinton provides a unique 36-digit GUID identifying your dealer integration. This is critical — integration cannot be completed without it. Contact Blackinton sales to register and obtain yours.
Add to the <HEAD> section of your hosting page.
<!-- PCS CSS -->
<link rel="stylesheet"
href="//build.blackinton.com/api/YOUR-TENANT-ID/css/?filename=pcs-core.css"
type="text/css" crossorigin="anonymous">Add to the <HEAD> section. Used as-is — no changes needed.
<link rel="stylesheet"
href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"
crossorigin="anonymous" referrerpolicy="no-referrer" />Add to the <HEAD> section. Replace the highlighted region with your Tenant ID.
<!-- PCS JS -->
<script
src="//build.blackinton.com/api/YOUR-TENANT-ID/script/?filename=pcs-core.js"
type="text/javascript" crossorigin="anonymous"></script>This HTML renders the PCS product configuration interface on your page.
<div class="pcs-iframe-loader"></div>
<iframe id="pcs_iframe" name="pcs_iframe"
src="//build.blackinton.com/YOUR-TENANT-ID/catalog"
class="pcs-iframe" scrolling="no" title="">
</iframe>To bypass catalog browsing and load a specific product, use the product URL with a style parameter.
<div class="pcs-iframe-loader"></div>
<iframe id="pcs_iframe" name="pcs_iframe"
src="//build.blackinton.com/YOUR-TENANT-ID/product/?style=B38"
class="pcs-iframe" scrolling="no" title="">
</iframe>Web Wizard (WW) is Blackinton's flagship B2B web application providing full access to order processing, tracking, and fulfillment. PCS transaction data can also be viewed and managed here.
https://app.blackinton.com
Navigate to Orders → PCS tab to view draft PCS orders. Use the Action menu to View, Edit, Print, Submit, or Delete an order.
Transmitted to Blackinton but not yet in production. Visible in the PCS tab. Can be reviewed and submitted here.
Fully submitted into the production workflow. Cannot be edited without reverting to Draft status first.
All API requests require an OAuth 2.0 Bearer token included in every request header.
Authorization: Bearer <YOUR-JWT-TOKEN>https://api.blackinton.com/v1
Authenticates and returns a JWT token used to access all API endpoints.
{
"ClientId": "cdeb6084-a4f9-42c2-b6dc-11c8c965970c",
"ClientSecret": "r1xIEqX4upJqadkCquec7nvAq",
"GrantType": "client_credentials"
}| Field | Required | Description |
|---|---|---|
ClientId | Required | 36-character GUID provided at application registration. |
ClientSecret | Required | 25-character secret created during registration. |
GrantType | Required | Must be client_credentials for app-to-app authentication. |
| 200 | Returns token, refreshToken, expires, clientId |
| 400 | Bad Request |
| 401 | Unauthorized |
| 429 | Too Many Requests |
Refreshes an expired token. Both old token and refresh token are invalidated; new ones issued.
{
"ClientId": "cdeb6084-a4f9-42c2-b6dc-11c8c965970c",
"Token": "<EXISTING-JWT-TOKEN>",
"RefreshToken": "r1xIEqX4upJqadkCquec7nvAq",
"GrantType": "refresh_token"
}Validates a product style number and returns its short description.
| 200 | {"style":"", "description":""} |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 429 | Too Many Requests |
Returns a paginated list of products updated since the specified date, optionally filtered by category.
| Parameter | Required | Description |
|---|---|---|
LastModifiedOn | Required | Date format YYYY-MM-DD. Returns products modified on or after this date. |
categories | Optional | Comma-separated CategoryID values, e.g. 76,101,102. |
limit | Optional | Max records to return. Default and max: 400. |
offset | Optional | Records to skip from the start of the result set. |
Creates a new order with either DR (Draft) or SU (Submitted) status.
{
"PcsOrderID": 641,
"DealerPO": "12345",
"CustomerPO": "K106639",
"Status": "DR",
"CreatedByLogon": "username",
"CarrierAccount": "W691V3",
"CarrierCode": "UPSN",
"CarrierServiceCode": "03",
"NotificationEmail": "[email protected]",
"ShipAddress": {
"Name": "Providence Police Department",
"Address1": "536 Atwells Ave",
"Address2": "Suite 100",
"City": "Providence",
"State": "RI",
"Postal": "02909",
"Country": "US",
"IsResidence": false
},
"ShipContact": {
"Title": "Chief",
"First": "John",
"Middle": "A",
"Last": "Smith",
"Phone": "4015551234",
"Email": "[email protected]",
"Department": "Operations"
},
"Items": [
{
"DesignKey": "980549bc-6461-468c-88ee-8d8071f36343",
"Price": "89.90",
"Qty": 1
}
]
}| Field | Type | Required | Notes |
|---|---|---|---|
| Order | |||
PcsOrderID | integer | Optional | External reference ID from the dealer's system. Stored for cross-reference but not used internally by PCS. |
DealerPO | string | Required | Dealer purchase order number. Alphanumeric, max 10 characters. |
CustomerPO | string | Optional | End-customer PO number. Max 25 characters. |
Status | string | Required | DR = Draft SU = Submitted. Use DR to save without triggering production. |
CreatedByLogon | string | Required | Logon of the user creating the order. Must be a valid PCS user with order-creation permission. Max 40 characters. |
NotificationEmail | string | Optional | One or more email addresses for order status notifications. Separate multiple addresses with a semicolon (;). Max 80 characters per address. |
| Carrier | |||
CarrierCode | string | Optional | Shipping carrier. Accepted values: FDXG (FedEx Ground), FDXE (FedEx Express), UPSN (UPS), USPS. |
CarrierServiceCode | string | Optional | Carrier service level code. Example: 03 = UPS Ground, 92 = FedEx Ground. Must be valid for the chosen CarrierCode. |
CarrierAccount | string | Optional | Third-party carrier account number to bill freight charges to. Max 25 characters. |
| ShipAddress | |||
ShipAddress.Name | string | Optional | Recipient or organization name. Max 60 characters. |
ShipAddress.Address1 | string | Required | Primary street address. Max 50 characters. See Address Validation below. |
ShipAddress.Address2 | string | Optional | Suite, floor, unit, or other secondary address line. Max 50 characters. |
ShipAddress.City | string | Required | City name. Max 40 characters. |
ShipAddress.State | string | Required | State or province code. Must be valid for the given Country. Max 10 characters. See Address Validation below. |
ShipAddress.Postal | string | Required | Postal / ZIP code. Format is validated against the expected pattern for the given country. Max 20 characters. See Address Validation below. |
ShipAddress.Country | string | Required | ISO 3166-1 alpha-2 country code (e.g. US, CA). Must exist in the PCS country reference table. See Address Validation below. |
ShipAddress.IsResidence | boolean | Optional | true if shipping to a residential address. Carriers may apply a residential surcharge. Defaults to false. |
| ShipContact | |||
ShipContact.Title | string | Optional | Contact's title or honorific (e.g. Chief, Sgt). Max 25 characters. |
ShipContact.First | string | Optional | Contact's first name. Max 25 characters. |
ShipContact.Middle | string | Optional | Contact's middle name or initial. Max 25 characters. Send "" to omit. |
ShipContact.Last | string | Required | Contact's last name. Max 25 characters. |
ShipContact.Phone | string | Optional | Contact phone number. Digits only, no formatting. Max 20 characters. Example: "4015551234". |
ShipContact.Email | string | Required | Contact email address. Max 80 characters. |
ShipContact.Department | string | Optional | Department or division within the organization. Max 50 characters. Send "" to omit. |
| Items | |||
Items[].DesignKey | string | Required | 36-character GUID identifying the PCS product configuration. Obtained from the PCS configurator. |
Items[].Qty | integer | Required | Order quantity. Range: 1 to 999,999. |
Items[].Price | decimal | Optional | Dealer-set retail price as a string-formatted decimal (e.g. "89.90"). Uses the configured suggested retail price if omitted. |
All ShipAddress fields are validated server-side in a strict, sequential order before the order is accepted. The first failure immediately stops processing and returns an error — no further fields are checked until the reported error is corrected and the request is resubmitted.
PCS checks fields in this order: Country → Address1 → City → Postal (presence) → Postal (format) → State (presence) → State–Country match. Correct each error one at a time and resubmit until the order is accepted.
ShipAddress.CountryUS, CA) recognised by PCS. The country value is used to validate both the postal code format and the state/province in the steps that follow.ShipAddress.Address1ShipAddress.CityShipAddress.PostalShipAddress.PostalUS, alphanumeric for CA). Leading/trailing spaces are ignored.ShipAddress.StateShipAddress.StateRI is valid for US, and ON is valid for CA — but not interchangeable between them.| Error Code | Field | Message | How to Fix |
|---|---|---|---|
51007 | ShipAddress.Country | shipAddress.Country is invalid | Supply a valid ISO 3166-1 alpha-2 code (e.g. US, CA). Three-letter codes, full country names, and unrecognised values are all rejected. |
51008 | ShipAddress.Address1 | shipAddress.Address1 is required | Provide a non-empty street address string. |
51009 | ShipAddress.City | shipAddress.City is required | Provide a non-empty city name. |
51010 | ShipAddress.Postal | shipAddress.Postal is required | Provide a non-empty postal or ZIP code. |
51022 | ShipAddress.Postal | shipAddress.Postal format is invalid for the given Country | Ensure the postal code matches the expected format for the country supplied (e.g. 5 digits for US). Extra or missing digits, or letters in a numeric-only field, will trigger this error. |
51011 | ShipAddress.State | shipAddress.State is required | Provide a non-empty state or province code. |
51021 | ShipAddress.State | shipAddress.State is invalid for the given Country | Use the correct abbreviation for the country supplied. State and province codes are country-specific — ON is a Canadian province and is not valid for US. Full state names are not accepted. |
Supply the country as a standard two-letter ISO code. PCS validates the code against a supported country list — if the code is not found, the entire address is rejected immediately and no further fields are evaluated.
"Country": "US" — United States"Country": "CA" — Canada"Country": "GB" — United Kingdom"Country": "AU" — Australia"Country": "DE" — GermanyAlways use the two-character uppercase ISO 3166-1 alpha-2 format.
"Country": "USA" — three-letter codes are not accepted"Country": "United States" — full names are not accepted"Country": "" — blank or null → ERR 51007"Country": "XX" — unrecognised code → ERR 51007The state or province code is validated against the country supplied in the same request. The same code can be valid for one country and invalid for another — always pair the correct state code with its matching country.
"State": "RI", "Country": "US" — Rhode Island"State": "CA", "Country": "US" — California"State": "TX", "Country": "US" — Texas"State": "NY", "Country": "US" — New York"State": "ON", "Country": "CA" — Ontario, Canada"State": "BC", "Country": "CA" — British Columbia, Canada"State": "ON", "Country": "US" — ON is Canadian, not a US state → ERR 51021"State": "Rhode Island", "Country": "US" — full names not accepted → ERR 51021"State": "ZZ", "Country": "US" — unrecognised code → ERR 51021"State": "", "Country": "US" — blank → ERR 51011The postal code is first checked for presence, then validated against the expected format for the country. Leading and trailing spaces are automatically ignored.
Each country enforces its own postal format. For example, US ZIP codes must be 5 digits — 4 digits or any letters will fail. Canadian postal codes follow an alternating letter-digit pattern. Always use the format standard for the country you are shipping to.
"Postal": "02909", "Country": "US" — 5-digit US ZIP"Postal": "10001", "Country": "US" — New York City ZIP"Postal": "90210", "Country": "US" — Beverly Hills ZIP"Postal": "K1A 0A9", "Country": "CA" — Canadian postal code"Postal": "M5G 2J3", "Country": "CA" — Toronto postal codeLeading/trailing whitespace is automatically trimmed before validation.
"Postal": "ABCDE", "Country": "US" — letters in a US ZIP → ERR 51022"Postal": "9290", "Country": "US" — only 4 digits, 5 required → ERR 51022"Postal": "029034", "Country": "US" — 6 digits, 5 required → ERR 51022"Postal": "", "Country": "US" — blank → ERR 51010"ShipAddress": {
"Name": "Riverside Police Department",
"Address1": "4102 Orange St",
"Address2": "Suite 200",
"City": "Riverside",
"State": "CA",
"Postal": "92501",
"Country": "US",
"IsResidence": false
}All checks pass. US is a valid country, all required fields are present, 92501 is a valid 5-digit ZIP, and CA is a recognised US state.
"ShipAddress": {
"Name": "Ottawa Police Service",
"Address1": "245 Elgin St",
"City": "Ottawa",
"State": "ON",
"Postal": "K2P 1L9",
"Country": "CA",
"IsResidence": false
}All checks pass. CA is a valid country, K2P 1L9 matches the Canadian postal format, and ON is a valid province for Canada.
"ShipAddress": {
"Name": "Dallas Sheriff Office",
"Address1": "133 N Riverfront Blvd",
"City": "Dallas",
"State": "TX",
"Postal": "75207",
"Country": "USA" ← must be 2-letter code
}Fails at Step 1. "USA" is not a recognised country code. Use "US" instead. No other fields are checked until this is corrected.
"ShipAddress": {
"Name": "Springfield PD",
"Address1": "800 E Monroe St",
"City": "Springfield",
"State": "IL",
"Postal": "627011", ← 6 digits, US expects 5
"Country": "US"
}Fails at Step 5. US ZIP codes must be exactly 5 digits. Use "62701".
"ShipAddress": {
"Name": "Vancouver RCMP Detachment",
"Address1": "2120 Cambie St",
"City": "Vancouver",
"State": "BC", ← BC is a Canadian province
"Postal": "10001",
"Country": "US" ← but Country is set to US
}Fails at Step 7. BC is not a US state. Either change Country to "CA" with a valid Canadian postal code, or use a valid US state code.
"ShipAddress": {
"Name": "Phoenix PD",
"Address1": "620 W Washington St",
"City": "", ← blank City
"State": "AZ",
"Postal": "85003",
"Country": "US"
}Fails at Step 3. City cannot be blank. Postal and State are not evaluated until this is corrected.
Update Order — Modify items or fields on a Draft (DR) order. Set "deleted": true on an item to remove it.
Submit Order — Change status DR → SU. Triggers production. All items re-validated.
{ "Status": "SU" }Get Orders by Status — Returns paginated list. Values: DR, SU, CO, CA, SH, H.
Get Order by ID — Returns a single order object. No status restriction.
Cancel Order — Sets status to CA. Order must be DR or SU.
{ "status": "CA" }Delete Order — Permanently deletes a Draft (DR) order. Submitted orders must revert to DR first.
Clone a Design — Creates a copy of an existing design and returns a new Design Key.
| 200 | {"newDesignKey":"..."} |
Print Design (PDF) — Returns a PDF of the design configuration details.
| 200 | Returns application/pdf file |
Get Design by Key — Returns full JSON details of a single design configuration.
| 200 | Single JSON object representing the design |
Returns a single catalog object including its full category structure.
| Parameter | Required | Description |
|---|---|---|
code | Required | A valid catalog code, e.g. pcs |
| 200 | Single JSON object representing the catalog and its category structure |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal System Error |