Resources and prompts¶

Resources¶

Reference material any connection may read, and templates that serve your own data under exactly the same rules as the matching tool. Generated from the running server.

URI	What it is
`freightright://guides/billing-and-documents`	Billing, customs, documents and events: reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://guides/pricing-and-booking`	Pricing, quoting and booking: reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://guides/querying`	Finding shipments: reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://reference/codes`	Codes and vocabulary: reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://reference/milestones`	Shipment milestones and dates: reference material about how Freight Right answers. The same for every customer; needs no permission.

Template	What it is
`freightright://rate-requests/{rate_request_id}`	A quote request: its status, the offer once Freight Right has quoted it, and the booking once one was requested. Needs permission to read quote requests.
`freightright://shipments/{reference}`	Everything Freight Right records about one shipment: routing, containers, recorded milestones and estimated or actual dates. Needs permission to read shipments.

Prompts¶

Ready-made starting points. A prompt is text: it authorizes nothing, and the tools it names enforce what they always enforce.

Prompt	What it asks for	Arguments
Arrivals this week (`arrivals-this-week`)	What is due to arrive in the next seven days.	none
Ask Freight Right's team (`ask-freight-right`)	A spot rate, a contract, booking help, a shipment problem, a correction or a feature.	`what`
Book a price I have seen (`book-an-offer`)	Prepare a booking for me to confirm myself.	`which`
Compare instant prices (`compare-instant-rates`)	Price one lane now and compare the offers.	`lane`
Potentially overdue shipments (`delayed-shipments`)	Shipments whose estimated date has passed with nothing recorded.	none
Landed cost of a shipment (`landed-cost-for-a-shipment`)	Freight charges, duty and fees of one shipment, per currency.	`reference`
My open quotes (`open-quotes`)	What is quoted, waiting or booked.	none
Price a container shipment (`price-a-container-shipment`)	Walk me through an FCL price check.	none
Price a pallet or crate shipment (`price-a-pallet-shipment`)	Walk me through an LTL or LCL price check.	none
Reconcile a purchase order (`reconcile-a-purchase-order`)	What of a PO shipped, in which containers, and what does not add up.	`purchase_order`
Ask Freight Right to quote (`request-custom-quote`)	For what instant prices do not cover.	`what`
Track a shipment (`track-shipment`)	Where is one shipment, and what happens next.	`reference`

What the reference documents say¶

Shipment milestones and dates¶

freightright://reference/milestones

Shipment milestones and dates¶

Estimated vs actual. A date with actual happened. A date with only estimated has not: it is a plan that moves. Never tell a customer something has happened because an estimate has passed.

What each date means - departure: the vessel, aircraft or truck left the origin port or facility. - arrival: arrival at the final air or ocean port of the main leg. NOT delivery. - delivery: the goods reached the final destination address. appointment is a booked delivery slot.

Milestones are recorded events, newest last. They come from carriers, terminals and our own operations, so their wording is theirs, not ours, show it, do not interpret it. A shipment with no recent milestone is not necessarily late: not every carrier reports every step.

Times are local to the event's own location, as recorded.

"Potentially overdue" means only that an estimated arrival or delivery date has passed with no actual date recorded. It is not a confirmed delay: ask Freight Right before telling a customer their shipment is late.

Tracking status and delivery state (newer environments). tracking_status is the chip Shipment Manager shows THIS user for the shipment or a container (code, label, since), the caller's own, so two users can see different ones; delivery_state is IN_TRANSIT or DELIVERED as Shipment Manager derives it. Both are null where the environment does not send them yet. A container's last_free_day is the last day it can stay at the terminal without storage charges, and available_for_pickup_at when the terminal made it available; contents are the package groups inside it, from Freight Right's pack items, empty means none are recorded, not an empty box.

What changed. freightright_list_shipment_events is the change signal: a feed of events (created, a milestone recorded, an ETA changed, arrived, delivered, a last free day set, available for pickup, a document added, an invoice added or paid, archived, a booking cancelled), oldest first, paged by cursor. updated_since on the list is NOT a change signal: every active shipment is re-stamped nightly.

Codes and vocabulary¶

freightright://reference/codes

Codes and vocabulary¶

Everything below is generated from the same table the tool schemas use, so it cannot fall behind them.

Places. A PORT is a UN/LOCODE (CNSHA Shanghai, USLAX Los Angeles) or, for air, an airport's IATA code (PVG, FRA). freightright_find_locations turns a place a customer NAMED into that code, use it rather than guessing, because a wrong code is location_not_found and nothing else. A DOOR is a postal code plus an ISO country code; the postal code is used exactly as sent, and needs no lookup.

Modes. FCL (full container load, ocean, priced by the container) · LCL (less than container load, ocean, priced by weight or volume, whichever is greater) · AIR (air freight, airport to airport or door to door) · LTL (less than truckload, road, door to door within the US, within Canada, and between them) · FTL (full truckload, road, door to door in the US, Canada and Mexico; quote requests only, never priced instantly).

A shipment’s transport_mode is not a pricing mode: SEA is the kind of move FCL and LCL price, AIR the kind AIR prices, and ROA or TRK the kind LTL and FTL price. A price check creates nothing and never becomes a shipment, a shipment exists once Freight Right books and operates it.

What each mode needs. FCL: needs containers, direction; refuses hazardous and temperature-controlled cargo, ask for a quote request instead · LCL: needs pieces OR totals, direction · AIR: needs pieces OR totals, direction · LTL: needs pieces, with the dimensions and weight of each handling unit, a DOOR at both ends; refuses direction, incoterm, port charges, customs and insurance, the API has no place for them on a truckload lane; ask for insurance in a quote request note · FTL: needs containers, a DOOR at both ends; refuses direction, incoterm, port charges, customs and insurance; and it is never priced instantly, it is a quote request.

FTL takes its equipment in the containers argument, as container sizes, the current API representation, and the same choices as the Shipment Manager trucking form. Anything else about the truck (trailer type, weight, loading) goes in the quote request note.

Containers. 20GP (20-foot general-purpose container) · 40GP (40-foot general-purpose container) · 40HC (40-foot high-cube container, taller than a 40GP) · 45HC (45-foot high-cube container). A container entry is a type and a quantity; at most 4 entries, so combine quantities of the same type.

Loose cargo. A piece group is any number of IDENTICAL pieces, with the dimensions and weight of ONE of them. At most 30 groups for LTL and 50 for LCL and AIR, a group can be hundreds of pallets, so that is rarely a limit in practice. LCL and AIR accept totals instead when the dimensions are unknown.

Packaging. PALLET (goods on a pallet) · SKID (goods on a skid, a pallet with no bottom deck) · BOX (a box) · CARTON (a cardboard carton) · CASE (a case) · CRATE (a wooden crate) · DRUM (a drum) · BUNDLE (items bundled together) · ROLL (a roll) · BAG (a bag or sack) · BALE (a bale) · COIL (a coil) · TUBE (a tube) · PIECE (a single unpackaged item) · PACKAGE (a package, when nothing more specific fits).

Freight class (LTL). A freight class is classified from the density, handling, stowability and liability of the goods, it is not a price setting. Give dimensions and weight and let it be estimated, or use the class on the customer’s own NMFC paperwork. Never choose a lower class to get a cheaper price: the carrier reweighs and rebills. Values: 50 · 55 · 60 · 65 · 70 · 77.5 · 85 · 92.5 · 100 · 110 · 125 · 150 · 175 · 200 · 250 · 300 · 400 · 500.

Units. Weight KG · LB · dimensions CM · IN · volume CBM · CFT. Decimals accepted: dimensions 2 places, weight 3, volume 4, money 2. More than that is refused rather than rounded, a rounded weight is a different shipment.

Accessorials. LIFTGATE (the truck needs a lift at that end, no loading dock or forklift there) · RESIDENTIAL (a home or a residential street rather than a commercial address) · LIMITED_ACCESS (a site a truck reaches with difficulty, a school, a farm, a construction site, a military base) · INSIDE (the driver carries the goods inside, past the threshold) · APPOINTMENT (the carrier must book a time slot before arriving). Each side needs a DOOR at that end; FCL accepts RESIDENTIAL only.

Insurance. Give the commercial value of the goods as insured_value_usd, in USD. Ocean and air only. LTL and FTL cannot be insured through this API; ask for insurance in a quote request note instead.

Customs. customs_brokerage adds clearance at the destination. SINGLE (a bond for this one entry, quoted separately, not in the offer) · ANNUAL (a continuous bond covering a year of entries, adds a charge to the offer), US imports only.

Direction. IMPORT (the customer is BUYING the goods and bringing them in) · EXPORT (the customer is SELLING the goods and sending them out). Required for FCL, LCL and AIR; not accepted for LTL or FTL.

Incoterms decide which port charges are included by default; omitted means FOB for an import, EXW for an export. EXW (Ex Works, the buyer takes over at the seller’s premises) · FCA (Free Carrier, the seller hands the goods to the buyer’s carrier) · FAS (Free Alongside Ship, the seller delivers beside the vessel) · FOB (Free On Board, the seller delivers on board at the origin port) · CFR (Cost and Freight, the seller pays carriage to the destination port) · CIF (Cost, Insurance and Freight, CFR plus the seller’s insurance) · CPT (Carriage Paid To, the seller pays carriage to the named place) · CIP (Carriage and Insurance Paid To, CPT plus the seller’s insurance) · DAP (Delivered At Place, the seller delivers, the buyer clears customs) · DPU (Delivered At Place Unloaded, the seller delivers and unloads) · DDP (Delivered Duty Paid, the seller delivers cleared, duties paid).

Service scope (on an offer, never sent): PORT_TO_PORT (port to port, nothing inland at either end) · DOOR_TO_PORT (collected at the origin address, delivered to the destination port) · PORT_TO_DOOR (collected at the origin port, delivered to the destination address) · DOOR_TO_DOOR (collected and delivered at addresses). It follows from choosing a PORT or a DOOR at each end, there is nothing to ask for.

Charges. Every charge has a category (ORIGIN · FREIGHT · DESTINATION · CUSTOMS · INSURANCE) and a basis (per container, per kg, per shipment, …). An offer's total is the sum of its charges. All amounts are sell prices for the customer.

Quote statuses. PENDING (with Freight Right’s pricing team) · QUOTED (there is an offer that can be booked) · DECLINED (Freight Right cannot quote it) · EXPIRED (the offer is no longer valid) · BOOKING_REQUESTED (a booking was asked for and Freight Right is reviewing it) · BOOKED (Freight Right confirmed the booking). A quote is read in full by its number with freightright_get_quote; its offer is there once it is QUOTED, BOOKING_REQUESTED or BOOKED.

Where a quote came from. PORTAL (created in Shipment Manager by the customer or by Freight Right) · RATE_REQUEST (created from a quote request) · INSTANT_BOOKING (created by booking an instant offer).

Identifiers. rc_… a price check · pj_… a running price check, the pricing_id collected with freightright_get_rate_offers · of_… an offer · rev_… the fingerprint of an offer exactly as shown · rfq_… a quote request · a quote number is an integer in Shipment Manager and is NOT a quote request id · a forwarder reference identifies a shipment.

Finding shipments¶

freightright://guides/querying

Finding shipments¶

Start from what the customer says, not from a list:

A reference of any kind, forwarder reference, house or master bill, container number, purchase order, freightright_find_shipments searches all of them at once and says which one matched.
"What is arriving this week", "what is still on the water": freightright_list_shipments with an arrival window, newest first.
One shipment in full: freightright_get_shipment with its forwarder reference.

Filters are applied by Freight Right, never by you: every answer says which filters it applied (applied_filters). If a filter is missing there, the results were withheld rather than shown unfiltered, say so, do not filter by hand.

Pages: when has_more is true, call again with cursor set to next_cursor and the SAME filters. Never invent a cursor.

The filters, and what they mean. traffic international (sea or air, crossing a border) or domestic (road inside one country) · transport_mode SEA, AIR, ROA, RAI, TRK, how it moves, not a pricing mode · shipment_status FREE TEXT matched exactly, often empty, so never invent one · archived false by default · updated_since an RFC 3339 timestamp, for syncing · arriving_from/arriving_to the estimated arrival at the FINAL port · delivering_from/delivering_to the estimated FINAL delivery to the address, a different event, often days later · departing_* the estimated departure · arrival_recorded/delivery_recorded whether an ACTUAL timestamp exists, so arriving_to=yesterday with arrival_recorded=false is what "possibly overdue" means.

A shipment nobody can see is not an error: a customer's account sees the shipments of its own organizations. A Freight Right administrator's connection sees every organization's; organization narrows a list to one of them. Organizations are named WITH their id everywhere (Acme Imports (ACMEIMPLAX)): the id is what organization takes, and a shipment's customer_organization_id and each party's organization_id carry the same ids.

What changed since last time is freightright_list_shipment_events, not updated_since (see the milestones reference). A shipment's billing, customs and documents have their own tools and permissions (freightright://guides/billing-and-documents).

Pricing, quoting and booking¶

freightright://guides/pricing-and-booking

Pricing, quoting and booking¶

Instant prices (freightright_get_instant_rates) ask carriers live. A NEW price check spends one unit of the customer's monthly allowance, so price once per lane and cargo, when the customer wants prices, never to explore. A slow answer comes back as status: PRICING with a pricing_id: collect it with freightright_get_rate_offers, do not price again.

Repeating a price check does not always cost a unit. An identical request for the same billing account, the same normalized request, not merely the same lane and cargo, joins the running check, or is served the retained one, and spends nothing; served_from says EXISTING_CHECK and the original priced_at is kept. A result is retained until bookable_until (at least a minute, at most four hours; fifteen minutes when an answer is complete without one, two minutes when it is not) and can be dropped sooner, because only the five most recent results per customer are kept. NEW_CHECK means this call started a check and spent a unit; it is not a promise that the carriers were asked again, since the API may answer a repeated request from its own cache.

An offer is a price, not a booking. Nothing is reserved. complete: false means a source did not answer; no offers with complete: true means there is no instant price for that lane.

Quote requests (freightright_submit_rate_request) ask Freight Right's team to price something instantly prices cannot: full truckload, Mexico trucking, unusual cargo, or simply a second opinion. Show the customer freightright_preview_rate_request first: it sends nothing. Sending the identical request twice within 30 days returns the first one.

Bookings are the customer's decision, always. freightright_prepare_instant_booking and freightright_prepare_rate_request_booking prepare one and give you a link; only the customer, signed in to Freight Right, can submit it there. Give them the link and say what it will book. Then freightright_get_booking_operation says what they decided. BOOKING_REQUESTED means our team is reviewing it; BOOKED means Freight Right confirmed it.

Billing. A price, a quote request and a booking are made for a billing account: an organization id (freightright_list_billing_organizations) or, for an account with no billable organization, the company name the customer gives. If several organizations exist and none is the default, ask the customer which. A Freight Right administrator names the client organization on every request, search it by name with query, confirm the match with them, and never guess an id, or a company name for a customer who has none.

Whose booking. Booking a quote request takes the account that created it, a current member of the organization it is billed to, or an address Freight Right shared its quote with; the request says may_book. An administrator reads every organization's requests but books only the ones their own account created, do not offer to book what the user cannot.

Sharing a quote is an administrator's: freightright_share_quote shares it with the e-mail addresses the user names. Each address then sees the quote once it signs in, with or without an organization, and can use its approval, booking-request and cancellation actions; an administrator's draft stays hidden until it is sent. Sharing sends no e-mail, and an address is removed on the quote page only. A quote row says shared_with_you when the user sees it only because it was shared with them.

Finishing a quote is an administrator's too, in this order, each step only when the user asks: freightright_get_quote_offers lists a draft quote's offers as its customer would see them (the first call prices it; ask again while it says it is still pricing); freightright_select_quote_offer makes the one the user chose the quote's offer, once; freightright_share_quote adds the people who should see it; freightright_send_quote sends it, the quotation e-mail goes only to addresses it is shared with, or to nobody.

A quote's public link (freightright_public_link) is a read-only link anyone holding it can open, without signing in, until the offer expires or it is turned off (freightright_change_public_link resets or turns it off, stopping the current URL for everyone). A customer's connection manages the links of the quotes they created or that are billed to one of their organizations, never of one only shared with them; an administrator's manages any quote's. It needs a selected offer that is still valid: a quote request has one once it is priced, and an administrator's draft is sent first. Give the link only to whom the user names.

Requests to Freight Right's team (freightright_create_request_draft) are for what no tool answers: a spot rate the instant tools could not price, a contract inquiry, help with a booking, a problem with a shipment, a record that is wrong, a feature the customer wishes for. First freightright_list_requests: an open request on the same ask is continued, never duplicated. A draft is private, nothing is sent, nobody is notified, and comes back with what Freight Right understood, what is missing and ONE question to ask; fill the answer in with freightright_update_request_draft at the revision you last saw. Then freightright_preview_request, show the customer the e-mail they would get, and freightright_submit_request with that revision ONLY when they say to send that version. The team answers by e-mail, to the account's own address; the organization comes from the account and is asked for only when the answer lists organization as missing. It needs a Freight Right account, which is free; an administrator's connection reads requests but files them on the staff page.

Money. Amounts are sell prices for this customer, in the currency of the offer. Never compare or add totals in different currencies. Never present a price as final after its valid_until.

Insurance is insured_value_usd: the commercial value of the goods, in USD, on FCL, LCL and AIR. LTL and FTL have no insurance field at all, for those, submit a quote request and ask for insurance in the note, with the value.

What each mode needs, in one line. Resolve the place first with freightright_find_locations, then:

FCL.containers (type and quantity) and direction. No hazardous or temperature-controlled cargo: that is a quote request.
LCL and AIR.direction, and either pieces (groups of identical pieces with the dimensions and weight of ONE) or totals (pieces, gross weight, volume). Never both.
LTL.pieces with dimensions and weight, a DOOR at both ends, inside the US and Canada. No direction, no incoterm, no insurance. freight_class is optional and estimated from density when omitted.
FTL, a quote request only. Equipment goes in containers as container sizes; everything else about the truck goes in the note.

Ask the customer for what is missing rather than assuming a value: a guessed weight is a wrong price.

Billing, customs, documents and events¶

freightright://guides/billing-and-documents

Billing, customs, documents and events¶

These are the sections of a shipment beyond its tracking, each behind its own permission, a connection made before they existed asks for the permission when a tool first needs it. The Freight Right API decides what the account may see, exactly as Shipment Manager does: a customer sees the invoices billed to its own organizations and the documents its account is allowed to see; a Freight Right administrator sees every organization's.

Billing (freightright_get_shipment_billing, permission "shipment billing"). Two independent feeds: the revenue invoices with every charge line (the Billing tab, code, description, quantity, unit price, amount, tax; sell prices Freight Right invoiced the customer) and the accounting invoices issued for the shipment (number, dates, total, outstanding amount as recorded, paid or cancelled, a PDF link that lives for minutes). A line can be in one feed and not the other, and nothing links an invoice to a container. Amounts are per currency: never add amounts in different currencies, and never compute "what is owed", outstanding_amount and the paid date ARE the status. An account whose billing is switched off is told so; the Billing tab is hidden for it too.

Invoices across shipments (freightright_list_invoices): the Billing page, open or settled, newest first, cursor-paged, with the open count and the outstanding amount per currency on the first page.

Customs (freightright_get_shipment_customs, the same permission): each declaration with its dates, ports, broker, declared value, total duty and fees (per declaration only, there is no per-line duty), agency statuses, the US customs facts and its lines with HTS codes. Nothing here is legal advice.

Documents (freightright_list_shipment_documents, freightright_get_shipment_document, permission "shipment documents"). The list carries no links. A link is asked for ONE document, is valid for minutes (expires_at), and is handed to the user at once, never stored, never reused, never summarised as if the file had been read: the tool does not read the file. A document type hidden from the account is simply absent; so are private documents.

Events (freightright_list_shipment_events, with the shipments permission). The change signal: oldest first, paged by cursor, at-least-once on a retry (dedupe by event_id). Billing events arrive only with the billing permission and DOCUMENT_ADDED only with the documents permission, otherwise they are absent, not an error. A scheduled job polls this feed with the customer's personal API token; an assistant connection is a person's.

An older build answered. During a rollout an instance that does not serve a section yet can answer: the tool says so and asks to try again in a minute. That is never "no such shipment" and never a reason to reconnect.