PBC Quotes Web Components - Self-Contained Demo

You're viewing 1.3.0

Read the integration guide for 1.3.0 and its component reference. For support status, see the version list.

Loader tags for 1.3.0: pin the exact version, or follow a rollup
Environment	Exact (1.3.0)	Latest 1.3.x	Latest 1.x
dev	`<script src="https://dev-logistics-pbc.awsmanlog10np.manheim.com/v/1.3.0/quotespbc-ui-loader.js"></script>`	`<script src="https://dev-logistics-pbc.awsmanlog10np.manheim.com/v/1.3/quotespbc-ui-loader.js"></script>`	`<script src="https://dev-logistics-pbc.awsmanlog10np.manheim.com/v/1/quotespbc-ui-loader.js"></script>`
stage	`<script src="https://stage-logistics-pbc.awsmanlog10np.manheim.com/v/1.3.0/quotespbc-ui-loader.js"></script>`	`<script src="https://stage-logistics-pbc.awsmanlog10np.manheim.com/v/1.3/quotespbc-ui-loader.js"></script>`	`<script src="https://stage-logistics-pbc.awsmanlog10np.manheim.com/v/1/quotespbc-ui-loader.js"></script>`
prod	`<script src="https://prod-logistics-pbc.awsmanlog10.manheim.com/v/1.3.0/quotespbc-ui-loader.js"></script>`	`<script src="https://prod-logistics-pbc.awsmanlog10.manheim.com/v/1.3/quotespbc-ui-loader.js"></script>`	`<script src="https://prod-logistics-pbc.awsmanlog10.manheim.com/v/1/quotespbc-ui-loader.js"></script>`

Release notes: 1.3.0

MINOR: New, backward-compatible features. Safe to adopt within this major.

F325061 (Correlation fields on OrderConfirmed and OrderFailed)

Order outcomes identify their order. Every OrderConfirmed and OrderFailed from <quote-order-component> now carries quoteId, itemRef, shipperId and vehicle, copied from the order that was submitted. A host on a page with several tabs or modals can match each outcome to its own request.
Every OrderFailed has the same shape. The fields sit at the top level, next to status: 'Failed', whether the BFF rejected the order or the widget failed it before or instead of sending it. The existing order and error keys are unchanged.
Nothing for existing hosts to change. The fields are optional, and one the host didn't send is left out of the event. New exported type: OrderCorrelation.
No change to the order API. The BFF adds the fields from the request it already holds, with no extra downstream call.
Open before release: the PO's confirmation of the UI-layer scope reading, and CP/CSA's sign-off on the field list (singular vehicle and both quoteId and itemRef).

F322342 / US2156061 (CP/CSA delivery address: ZIP and address max length)

The CP/CSA Transportation Quote widget's (<quote-order-component>) delivery address form now limits what can be typed to what the quote service accepts, and says what to fix instead of "Unable to get transportation quote at this time. Please try again later.":

The ZIP Code takes at most 5 characters for a US delivery stop (as OVE got in US2156059).
Address Line 1 and Address Line 2 take at most 75 each (as OVE got in US2151524).

No host-facing contract change → PATCH. No attribute, event or type is added, renamed, removed or retyped. Two host-observable differences: a host-supplied delivery Address Line 1 or 2 over 75 characters now gets prices, instead of the unavailable screen; and a host move with no delivery street address shows "Address Required" straight away. <ready-contact-quote> and <ready-zipcode-quote> are unaffected.

US2174643 (Integration guide and host-facing help on each version's example page)

Each version now publishes its own integration guide at /v/X.Y.Z/integration-guide.html, and the version list links to it. The guide has been corrected: every example uses the attributes the widgets actually take (api-config and quote-request; the old token, pbc-url and partnerid attributes never existed), every loader URL names the version you're reading about, and a new section explains when to pin /v/X.Y.Z/ and when to use the /v/M.m/ and /v/M/ rollups. It ends with a property and event reference generated from the components' code.

Each version's example page now opens with "You're viewing X.Y.Z" and copy-ready loader tags for dev, stage and prod. On a deployed page the forms point at that environment's BFF, so pasting a token is enough to try a widget. A table explains the "currently unavailable" and "Contact Ready Logistics" states, each form can copy its setup as HTML, React or Angular, and each event log shows the message types it can receive. On the production page, a warning beside the quote/order form says orders placed there are real.

No host-facing contract change → MINOR (a new capability). No tag, attribute, event or loader path changes. Versions 1.0.x–1.2.x have no guide page.

US2167551 (Version index page and per-version release notes)

The PBC's address now shows a list of its published versions, newest first. Each one says whether it's Current, Supported, Superseded or Unsupported, and links to that version's example page. From 1.3.0 on, each version's example page also carries its own release notes and changelog, so you can see what changed before you move a pin. Versions 1.0.x–1.2.x still load exactly as before, but they aren't on the list.

No host-facing contract change → MINOR (a new capability). No tag, attribute, event or loader path changes. Pinned /v/X.Y.Z/ URLs and the /v/M/ and /v/M.m/ rollups behave as before.

Changelog: 1.3.0

F325061 (Correlation fields on OrderConfirmed and OrderFailed)

OrderConfirmed and OrderFailed now say which order they are about. quote_bus is shared by the whole page, so every tab or modal hears every order outcome; until now a <quote-order-component> host couldn't tell whether a confirmation was for its own request.

Additive host-facing change → MINOR. Only new optional fields are added. Nothing is removed, renamed or retyped, and OrderSubmitted is unchanged.

Added — for hosts (`<quote-order-component>`)

OrderConfirmed (an OrderResponse) gains quoteId, itemRef, shipperId and vehicle (vin, isOperable and description with year/make/model/subModel), next to the existing orderId, confirmationNumber and status.
OrderFailed gains the same four fields, plus status: 'Failed', at the top level. The existing order and error keys stay as they were. A business rejection passes the BFF response through, so it may also carry orderId and confirmationNumber.
Each value is the one on the submitted order, the same as in OrderSubmitted's order, and is echoed unchanged. A field the host left out of quote-request is absent from the event. One the host sent as '' comes back as ''.
vehicle is singular because an order has one vehicle. It has the same shape as order.vehicle.
New exported type OrderCorrelation.

For maintainers

The BFF adds the fields. OrderService copies them from the OrderRequestModel onto the POST /Order response, for both Confirmed and business Failed results. The order API (ReadyProxy) request and response mapping in OrderApiClient is unchanged, and no extra downstream call is made.
The BFF's JSON settings moved from Program.cs into Startup/JsonOptionsExtensions.AddBffJsonOptions(), unchanged, so tests can serialize through the options the app actually registers.
The widget passes the BFF's fields through. OrderConfirmed is still the response verbatim. A business OrderFailed now spreads the response next to order. The widget doesn't fill in fields an older BFF didn't send.
The exception is the widget's own failures (invalid_contact, not_configured, service_unavailable). There is no BFF response on these paths, and the first two never reach the BFF, so the widget takes the fields from the order it built. That keeps every OrderFailed the same shape. Fields the order doesn't carry are left off, not sent as undefined — BroadcastChannel would otherwise deliver the key, and the BFF path omits it.
Scope check pending with the PO. F325061 lists UI-layer enrichment as out of scope. These three paths are the only place the widget fills fields itself, and only because no BFF response exists there. Confirm this reading on the feature before release; if it's rejected, those three OrderFailed events would carry no correlation fields at all.
Field list still to be confirmed with CP/CSA. The feature lists quoteId or itemRef, and both are sent. If CP/CSA asks for a vehicles array instead, that is a breaking rename and should be settled before release.

F322342 / US2156061 (CP/CSA delivery address: ZIP and address max length)

Changed — behaviour (`<quote-order-component>` only)

A US ZIP accepts at most 5 characters. This applies when the delivery country is US or USA (any case, spaces ignored), which is the same rule the ZIP validation uses. A host that omits the country gets the existing US default. Typing stops at 5, and phones and tablets show a numeric keypad.
An empty country now counts as US, the same as OVE. Before this change CP/CSA read a host-supplied empty country ("country": "") as non-US. Now it gets the US rules: 5 characters, numeric keypad, the 5-digit format check and the same quote-eligibility check. An omitted country was already US.
Outside the US, the postal code is free text up to 10 characters. Any character is accepted, including hyphens (01310-100). Nothing is filtered, and only the existing "required" check applies.
Typing is limited, never corrected. A letter in a US ZIP stays in the field and is flagged by the existing validation on blur.
Pasted text over the limit is cut without a message. A pasted 85004-1234 becomes 85004, as on OVE.
A ZIP+4 can no longer be typed. One supplied by the host is kept whole, is fully visible, is still valid, and is sent unchanged.
ZIP validation and all ZIP messages are otherwise unchanged.
Address Line 1 and Address Line 2 accept at most 75 characters each. Typing stops at 75, spaces count, and pasted text over 75 is cut to 75.
A full address line says so. At exactly 75 characters, whether typed, pasted or host-supplied, "Maximum 75 characters reached." shows under the line as grey help text. It is not an error: 75 is valid, and Review Quote still works. It goes away when a character is deleted, and any message on the field replaces it.
A host delivery address line over 75 is flagged and sent empty. The field shows the host's value in full, with "Address must be 75 characters or fewer." (Address Line 1) or "Address Line 2 must be 75 characters or fewer." under it, straight away. That line is sent empty in every quote request, so prices still show; the address is never shortened. Review Quote stays disabled until the line is 75 or fewer. Fixing it doesn't request a new quote, and the order carries the corrected address. Unlike OVE, the quote is not blocked: CP/CSA shows prices, as it already does for a host that passes no street address.
A quote-service length error for the delivery Address 1/2 shows under that field, instead of "Unable to get transportation quote…", and the options stay on screen. The message is the service's own, with the field name made readable: "Maximum length for 'Address1' is 50" shows as "Maximum length for Address is 50." So if the service ever lowers its limit, the shipper sees the real number. It is matched only when the error names the delivery stop's Address1/Address2 and its message is the max-length one. Any other error keeps the unavailable screen, as before. Because nothing was priced, fixing that line and leaving the field requests a new quote, the one address edit that does. Because the widget never sends a line over 75, this is a safety net.
No street address from the host shows "Address Required" straight away, as a missing ZIP already does. Before, it appeared only after the shipper had left the field. Prices still show, and Review Quote stays disabled until Address Line 1 is filled in. A host-supplied address still gets the message only after the shipper leaves the field.
Address Line 2 is now validated for length (it was never validated before). It stays optional. The pickup address and contact fields are unchanged.

Internal

delivery-address-form takes DELIVERY_ZIP_MAX_LENGTH and NON_US_POSTAL_CODE_MAX_LENGTH from utils/deliveryZip.ts. The choice between them is the shared appliesUsZipRule from the same file, which types/type-guards.ts now uses too, so the limit, the keypad, the shape check and quote eligibility always agree. The component's and type-guards.ts's own copies of the country check are removed.
The ZIP box width is unchanged. Its 120px column already shows five digits and a ZIP+4 in full; a real-browser test now measures that. OVE's calc(5ch + 18px) was not copied, since it would cut off a host ZIP+4 here.
The address rules reuse utils/deliveryAddress.ts: the limit, the length errors, the hint, and the quote-error mapping. deliveryAddressErrorsFromQuoteErrors gains an optional { serviceWording: true } (used by CP/CSA only) and readableServiceLengthMessage; OVE's behaviour is unchanged.
New @internal props:
- delivery-address-form.address2Error
- pickup-delivery-component.deliveryAddress2Error
addressRequiredError / deliveryAddressRequiredError keep their names, but now carry Address Line 1's length or required message.
quote-order-component sends a derived pricing request; its quoteRequest is never modified. isSubmittableDeliveryAddress now also checks both lines' length.
The delivery-address-form E2E spec now adopts the component's stylesheet. The harness does not apply styleUrl, so earlier measurements had been taken against browser defaults.

US2174643 (Integration guide and host-facing help on each version's example page)

For hosts

Token format. The token is sent exactly as given, so include the bearer prefix. The guide now says so.
The guide's BFF table lists the dev, stage and prod BFF hosts. Its examples still point at dev.
The <quote-order-component> reference now appears in the generated component docs and TypeScript types. A stray JSDoc tag in its description had hidden it from both.

For maintainers

scripts/build-pages.js runs after stencil build in npm run build, the Docker build and CI. It renders the guide with pinned marked (GitHub-compatible heading ids), substitutes {{version}}, removes relative and GitHub links (in-page anchors are kept), and fills the example page's placeholders. It fails on a dead in-page link, raw HTML outside code, a link whose scheme isn't https: or mailto:, a leftover placeholder, a broken extraction marker, or a public component missing from Stencil's docs-json output. Under npm start (Aspire), the dev server builds both pages on each request instead (scripts/dev-pages.js), and start now passes --docs so the watch build keeps docs-json current.
stripInternalLinks moved to src/quotespbc-ui/scripts/strip-internal-links.js so the Docker build can use it. The release scripts re-export it unchanged.
The example page is reordered for hosts. A collapsed Maintainer tools section at the end holds the Interstate status, the cache-busting test centre and the release notes guidance. The old combined "Copy Customer Test HTML" button is replaced by a copy button on each form.
New tests: npm run test:scripts (CI step "Page build tests", with coverage reported to Sonar), and version-list checks P20–P22 in scripts/verify-version-rollups.sh.
The container also checks the copied integration-guide.html and example-usage.js after each publish.

US2167551 (Version index page and per-version release notes)

For hosts

/ lists the published versions. So do /index.html and any other unknown path. The list shows a version only when its example page has release notes, which every release from 1.3.0 on has. It also lists the /v/M/ and /v/M.m/ rollup links whose targets are listed. The page has no JavaScript and is never cached.
Support status. The newest version of each of the 3 newest majors is supported: the newest of all is Current, and the newest of each other one is Supported. Other versions in those majors are Superseded, with a link to the newest in their line, and versions in older majors are Unsupported. This policy is provisional until ADR 0004 is accepted.
Each version's example page is /v/X.Y.Z/example-usage.html. The old root dev page is no longer published, and no version folder has an index.html. The page's "Copy test HTML" button now copies a snippet that loads the version you're viewing, with api-config and quote-request attributes that match the components' API and an empty token.

For maintainers

Prepare release writes the release notes. A new Write release notes step takes V's changelog sections, renders them through the GHES markdown API, removes relative links and links to this GitHub, and writes them into src/quotespbc-ui/src/example-usage.html in the release commit. A section's ### Release notes subsection is the host-facing summary; a section without one shows "No release notes", and the run warns. Dry runs preview the same warnings and write nothing.
A fourth release-merge check. The Main Pipeline creates release/V only if the example page at the merge carries release notes marked for V.
PBC_SUPPORTED_MAJORS (Dockerfile default 3, overridable per task definition) sets how many majors are supported. An invalid value stops the container at start.
The test page moved. It's src/quotespbc-ui/src/example-usage.html, at http://localhost:3333/example-usage.html locally, and the Aspire dashboard links there. src/index.html is a local placeholder. The build no longer rewrites a committed file: cache-busting stamps only www/example-usage.html.
The PR template asks for a ### Release notes subsection, an update to the page's maintainer section when the release process changes, and a hotfix forward-port that leaves out the example-usage.html change.
Hotfixes update the release notes by hand; see docs/release-process.md. Hotfixes of 1.0.x–1.2.x skip this.
Rolling back to an image from before this change brings back the old root dev page at / until a newer image is deployed.

What you see, and why

What you see	Why
"This transportation quote is currently unavailable. Please try again later."	The token in `api-config` is missing, expired or invalid, or `quote-request` is missing the move details: at least two stops and one vehicle. Fix your configuration; the shipper cannot resolve this by calling.
"Unable to retrieve transportation pricing at this time." with a Contact Ready Logistics link	No transport option could be priced for this move, or the pricing service failed. The configuration is accepted; the shipper can try again or call.
A message under a field (ZIP code, phone, email)	That input is invalid. The shipper corrects it and continues; nothing is sent until it is valid.

Ready contact Quote Component Test Form

Test all props: Update the values below and click "Update Component" to test different prop values

Address: Address 2: City: State: Dropoff Zipcode: API Token:

The widget shows "This transportation quote is currently unavailable" until a token is entered.

BFF URL: Quote ID: PartnerId: VIN: Pickup Zipcode: Is Operable:

LIVE COMPONENT PREVIEW:

Ready Contact Quote — Event Log

Message types and payloads

Example Event Payload

Quote Created Event:

### Example Event Payload

// Example of event.data when a quote is successfully created
{
  "eventType": "QuoteCreated",
  "eventBody": {
    "currency": "USD",
    "discount": 0,
    "discountCurrency": "USD",
    "distance": 11,
    "distanceLabel": "MI",
    "expirationDate": "2025-09-22T18:31:21Z",
    "maxDaysToDeliver": 3,
    "minDaysToDeliver": 2,
    "price": 93,
    "quoteId": "f2d1cce1-e1fe-4105-8070-7c6617f6dc11",
    "quoteRef": "202509001623111",
    "quoteSubType": "",
    "quoteType": "Standard",
    "stops": [
      {
        "distance": 0,
        "address1": "",
        "address2": "",
        "city": "Phoenix",
        "country": "US",
        "refId": "S1",
        "state": "AZ",
        "zip": "85044"
      },
      {
        "distance": 11,
        "distanceLabel": "MI",
        "address1": "",
        "address2": "",
        "city": "Phoenix",
        "country": "US",
        "refId": "S2",
        "state": "AZ",
        "zip": "85040"
      }
    ],
    "vehicles": [
      {
        "currency": "USD",
        "description": "1991/Acura/Legend/L",
        "descriptionDetails": {
          "make": "Acura",
          "model": "Legend",
          "subModel": "L",
          "year": "1991"
        },
        "discount": 0,
        "discountCurrency": "USD",
        "predictedBasePrice": 0,
        "price": 93,
        "priceLineItems": [
          {
            "currency": "USD",
            "description": "FixedRate",
            "price": 93
          }
        ],
        "vehicleSize": "S",
        "weight": "3300",
        "weightUnit": "pounds",
        "dropOffId": "S2",
        "isEnclosed": false,
        "isOperable": true,
        "pickUpId": "S1",
        "vin": "JH4KA7561MC010714"
      }
    ]
  }
}

Quote Error Event:

// Example of event.data when an error occurs during quote processing
{
  "eventType": "QuoteError",
  "eventBody": {
    "errors": [
      {
        "code": "quotes_api.bad_request",
        "message": "An error occurred while calculating distance: Route at index 0: Stop at index 1: No matching postal code found Problem: [N/A] 11111 , ErrorId:fc26f1b3-5226-43b2-8837-269cc14b8c2d"
      }
    ]
  }
}

Snippet format:

Ready Zipcode Quote Component Test Form

Test zipcode props: Update the values below and click "Update Zipcode Component" to test different prop values

BFF URL: API Token:

The widget shows "This transportation quote is currently unavailable" until a token is entered.

PartnerId: VIN: Pickup Zipcode: Dropoff Zipcode: Is Operable: VDP Mode:

Parent-supplied ZIP (VDP mode — F306320 AC-4 / AC-5)

Sets quote-request on the live component, as an OVE VDP would. Tick VDP Mode above and press Update Zipcode Component first, then change the ZIP here — the quote refreshes with no remount and no GO button. Clear it and the blue box stays put, showing “Enter a zip code to receive a delivery estimate.” in place of the price; enter a partial ZIP (e.g. 3032) and it does the same, since nothing was quoted.

ZIP to supply:

LIVE ZIPCODE COMPONENT PREVIEW:

Ready Zipcode Quote — Event Log

Message types and payloads

Example Event Payload

Quote Created Event:

### Example Event Payload

// Example of event.data when a quote is successfully created
{
  "eventType": "QuoteCreated",
  "eventBody": {
    "currency": "USD",
    "discount": 0,
    "discountCurrency": "USD",
    "distance": 11,
    "distanceLabel": "MI",
    "expirationDate": "2025-09-22T18:31:21Z",
    "maxDaysToDeliver": 3,
    "minDaysToDeliver": 2,
    "price": 93,
    "quoteId": "f2d1cce1-e1fe-4105-8070-7c6617f6dc11",
    "quoteRef": "202509001623111",
    "quoteSubType": "",
    "quoteType": "Standard",
    "stops": [
      {
        "distance": 0,
        "address1": "",
        "address2": "",
        "city": "Phoenix",
        "country": "US",
        "refId": "S1",
        "state": "AZ",
        "zip": "85044"
      },
      {
        "distance": 11,
        "distanceLabel": "MI",
        "address1": "",
        "address2": "",
        "city": "Phoenix",
        "country": "US",
        "refId": "S2",
        "state": "AZ",
        "zip": "85040"
      }
    ],
    "vehicles": [
      {
        "currency": "USD",
        "description": "1991/Acura/Legend/L",
        "descriptionDetails": {
          "make": "Acura",
          "model": "Legend",
          "subModel": "L",
          "year": "1991"
        },
        "discount": 0,
        "discountCurrency": "USD",
        "predictedBasePrice": 0,
        "price": 93,
        "priceLineItems": [
          {
            "currency": "USD",
            "description": "FixedRate",
            "price": 93
          }
        ],
        "vehicleSize": "S",
        "weight": "3300",
        "weightUnit": "pounds",
        "dropOffId": "S2",
        "isEnclosed": false,
        "isOperable": true,
        "pickUpId": "S1",
        "vin": "JH4KA7561MC010714"
      }
    ]
  }
}

Quote Error Event:

// Example of event.data when an error occurs during quote processing
{
  "eventType": "QuoteError",
  "eventBody": {
    "errors": [
      {
        "code": "quotes_api.bad_request",
        "message": "An error occurred while calculating distance: Route at index 0: Stop at index 1: No matching postal code found Problem: [N/A] 11111 , ErrorId:fc26f1b3-5226-43b2-8837-269cc14b8c2d"
      }
    ]
  }
}

Snippet format:

Responsive Layout Test (F306320)

The widget stacks the quote under the ZIP entry when its container is squarish, and collapses to a single ~60px strip — quote to the right of the ZIP entry — at 800px and above. The switch is the component's wide-breakpoint prop (default 800), measured against the component's own width, so resizing the browser window proves nothing on its own: drag the container's bottom-right corner or use the presets.

One threshold, and the whole quote on a single line from it — logo, price, delivery estimate, vertical rule, disclaimer. The card is a flat 60px at every width from 800px up. That fit is bought with smaller type in the strip only (delivery 11px, disclaimer 8px, price 16px, against 16/10/24 in the stacked card), leaving comfortable slack at 800px. The logo is deliberately not scaled: at 30px it is what sets the strip's height, so shrinking it would take the card under 60px.

Container width:

VDP Mode: wide-breakpoint:

RESIZABLE CONTAINER — drag the bottom-right corner

Quote / Order Component Test Form (F255314)

Test all props: Update the values below and click "Update Component" to render the component with a different configuration. The BFF URL defaults to this host's own BFF (https://localhost:7100 when served locally under Aspire).

This is the production page. Orders placed from this form are real orders.

BFF URL: API Token:

The widget shows "This transportation quote is currently unavailable" until a token is entered.

Order Source: Customer ID: User Email: Contact Name: Contact Phone: Contact Email: Partner ID: Payer ID: Shipper ID: Item Ref: VIN: Year: Make: Model: Sub Model: Is Enclosed: Is Operable: Contact Required: Pickup Address: Pickup Address 2: Pickup City: Pickup State: Pickup Zipcode: Pickup Country: Delivery Address: Delivery Address 2: Delivery City: Delivery State: Delivery Zipcode: Delivery Country:

LIVE COMPONENT PREVIEW:

Quote / Order — Event Log

Message types and payloads

`eventType`	`eventBody`	When
`pbc:ready`	(none)	Loaded and configured. Also fires again after each re-quote
`pbc:error`	`{ reason: 'unavailable' }`	Config/token rejected, or no option could be priced
`MultiQuoteCreated`	`MultiQuoteResponse`	Quotes returned
`QuoteError`	`{ errors: [{ code, message }] }`	Quote request failed — carries the reason
`OrderSubmitted`	`{ order }`	Each submission attempt
`OrderConfirmed`	`OrderResponse`	Order placed
`OrderFailed`	`{ status, error, orderId?, confirmationNumber?, quoteId?, itemRef?, shipperId?, vehicle?, order }`	Order rejected, or could not be sent

Four things to know before you write the handler

1. OrderSubmitted fires once per attempt, not per order. Submission is not idempotent, so a shipper retrying after a failure produces a second event for the same order. Deduplicate on quoteId if you record attempts.

2. OrderFailed can arrive with NO preceding OrderSubmitted. Two cases reject the order before anything is sent — an invalid contact, and a widget that has lost its api-config. If your handler marks an order "pending" on OrderSubmitted and resolves it on OrderConfirmed/OrderFailed, it will receive a resolution for something it never marked pending. Key your state off the order itself, not off having seen OrderSubmitted.

3. pbc:error tells you the widget is unavailable; QuoteError tells you why. They are different signals and both can fire for one failure. Listen for QuoteError if you want to distinguish a bad postal code from an expired token from an outage.

4. Match an outcome to your request with its correlation fields. quote_bus is shared by the whole page, so every tab or modal hears every OrderConfirmed and OrderFailed. Both carry quoteId, itemRef, shipperId and vehicle at the top level, copied from the order that was submitted — the same values OrderSubmitted carries in order. Compare them with what you supplied and ignore events that aren't yours. Values are echoed exactly: a field you left out of quote-request is absent, and one you sent as '' comes back as ''. itemRef, shipperId and vehicle.vin are your own values, so they are the ones to match on. quoteId is the quote the shipper picked, which you supplied nothing for; it is useful only if you captured it from that widget's OrderSubmitted.

A business rejection from the order service passes its whole response through, so an OrderFailed may also carry orderId and confirmationNumber. Treat both as optional on either event — don't write a type guard that rejects an OrderFailed that has them.

`error.code` values you may see on `OrderFailed`

Code	Meaning	Was anything sent?
`invalid_contact`	Phone or email failed validation	No
`not_configured`	Widget lost its `api-config` before submitting	No
`service_unavailable`	The order service could not be reached	Yes, outcome unknown
(from the BFF)	Business rejection — code and message come from the service	Yes, rejected

service_unavailable is the only one where the order may have reached the service, so treat it as indeterminate rather than as a clean failure.

Privacy note. OrderSubmitted and OrderFailed carry the full order, which includes the contact name, phone and email — deliberately, since you own the contact and need it to fulfil the order. Once you set user-email, that address rides along too. Treat those events as containing personal data when deciding what to log.

Response shapes

MultiQuoteResponse {
  quotes: {                          // always contains all three keys
    open?: TransportPriceOption,
    enclosed?: TransportPriceOption,
    expedited?: TransportPriceOption,
  },
  isHighValueVehicle: boolean,
  status: 'Successful' | 'Partial' | 'Failed',
}

TransportPriceOption {
  price: number | null,              // null when this option could not be priced
  currency: string | null,
  minDaysToDeliver: number | null,
  maxDaysToDeliver: number | null,
  expirationDate: string | null,     // UTC
  quoteId: string | null,
  error: { code, message } | null,
}

OrderResponse {
  orderId?: string,
  confirmationNumber?: string,
  status: 'Unknown' | 'Confirmed' | 'Failed',
  error?: { code, message },
  // Correlation fields, echoed from the submitted order:
  quoteId?: string,
  itemRef?: string,
  shipperId?: string,
  vehicle?: { vin?, isOperable, description?: { year?, make?, model?, subModel? } },
}

A Partial status is normal, not an error — one option can price while another fails. The widget handles the display; you only need status if you record the outcome.

Snippet format:

Maintainer tools

✅ Interstate Design System Integrated!
This page includes NO Interstate dependencies in the HTML. All Interstate styling and components are automatically loaded by your web components.

Checking Interstate CSS...

Checking Interstate Components...

Checking Cache Busting...

Key Benefits:

Host websites don't need to include Interstate CSS or JavaScript
Components work consistently across different websites
Automatic fallback styling if Interstate CDN is unavailable
Progressive enhancement with full Interstate features when available

Cache Busting Test Center

Test automatic cache busting: Monitor how cache parameters ensure fresh component loading

Current Cache Status

              Loading cache version...
            

Scanning for cache parameters...

Test Actions

How to Test Cache Busting:

Open browser DevTools → Network tab
Click "Check Cache Parameters" to see current version
Run npm run build in terminal to generate new version
Refresh this page and check for new version numbers
Look for ?v=timestamp.hash parameters on JS files

Cache Test Log

            Ready for cache busting tests...
          

For maintainers: how releases, release notes and the changelog are made

What MAJOR, MINOR and PATCH mean for a host

MAJOR: Breaking changes. Upgrade deliberately and read the changelog first.
MINOR: New, backward-compatible features. Safe to adopt within this major.
PATCH: Fixes only. No contract change.

Labelling pull requests

Label a pull request to main semver:minor when it adds to the host-facing contract, or semver:major when it breaks it. An unlabelled pull request counts as a patch. Prepare release takes the highest label merged since the last release.

Writing a changelog entry

Add a section at the top of docs/changelog.md headed ## [Unreleased] — <story> (<title>). Start it with a ### Release notes subsection written for hosts: what changed for them, and what they need to do, if anything. The rest of the section is the changelog. A section without release notes shows "No release notes" on this page, and Prepare release warns about it.

Cutting a release

Run the Prepare release workflow with dry_run on. Its summary shows the version, the pull requests it counts, and the release notes it would write, with a warning for each section that has none.
Run it again with dry_run off. It opens a release pull request that sets the version, converts the changelog headings, and writes this page's release notes for that version.
Review the release pull request, including the release notes on this page: they are what hosts read.
Merge it, and merge nothing else to main until it has merged. The Main Pipeline then creates the release branch, after checking that this page's notes name the version.

Hotfixes

Follow the hotfix steps in the README. On the hotfix branch, also update this page's release notes by hand: render the hotfix's changelog sections, replace what is between the release-notes markers, take out relative links and links to GitHub, and set the start marker to the hotfix version. The reviewer checks the marker. Hotfixes of 1.0.x to 1.2.x skip this, because those versions are not listed. The forward-port pull request to main leaves out the change to this page, as it leaves out npm version.

Where the process is maintained

README.md (Branches, labels and releases), docs/release-process.md and .github/workflows/prepare-release.yml. When the process changes, update this section too.

✅ Interstate Integration Active

PBC Quotes Web Components - Self-Contained Demo

You're viewing 1.3.0

Release notes: 1.3.0

F325061 (Correlation fields on OrderConfirmed and OrderFailed)

F322342 / US2156061 (CP/CSA delivery address: ZIP and address max length)

US2174643 (Integration guide and host-facing help on each version's example page)

US2167551 (Version index page and per-version release notes)

Changelog: 1.3.0

F325061 (Correlation fields on OrderConfirmed and OrderFailed)

Added — for hosts (<quote-order-component>)

For maintainers

F322342 / US2156061 (CP/CSA delivery address: ZIP and address max length)

Changed — behaviour (<quote-order-component> only)

Internal

US2174643 (Integration guide and host-facing help on each version's example page)

For hosts

For maintainers

US2167551 (Version index page and per-version release notes)

For hosts

For maintainers

What you see, and why

🧪 Ready contact Quote Component Test Form

Ready Contact Quote — Event Log

Example Event Payload

🧪 Ready Zipcode Quote Component Test Form

Ready Zipcode Quote — Event Log

Example Event Payload

📐 Responsive Layout Test (F306320)

🚚 Quote / Order Component Test Form (F255314)

Quote / Order — Event Log

Four things to know before you write the handler

error.code values you may see on OrderFailed

Response shapes

🚀 Cache Busting Test Center

📊 Current Cache Status

🧪 Test Actions

🎯 How to Test Cache Busting:

📋 Cache Test Log

What MAJOR, MINOR and PATCH mean for a host

Labelling pull requests

Writing a changelog entry

Cutting a release

Hotfixes

Where the process is maintained

Added — for hosts (`<quote-order-component>`)

Changed — behaviour (`<quote-order-component>` only)

Ready contact Quote Component Test Form

Ready Zipcode Quote Component Test Form

Responsive Layout Test (F306320)

Quote / Order Component Test Form (F255314)

`error.code` values you may see on `OrderFailed`

Cache Busting Test Center

Current Cache Status

Test Actions

How to Test Cache Busting:

Cache Test Log