Gives shippers, carriers and 3PLs visibility into freight charges as they evolve — reclassifications, reweighs and accessorial changes mid-shipment rather than weeks later on the invoice. The only LTL specification committed to the public DSDC repositories.
openapi: 3.0.0
info:
title: Preliminary Freight Charges (PFC) API
description: |
The Preliminary Freight Charges (PFC) API proactively notifies responsible parties (debtors or their authorized agents, including consignees when designated as agents) that a motor carrier has created a freight bill for a shipment associated with that party. Further notifications occur when the bill is updated or removed from their account.
## Key Features
- Proactive freight charge visibility throughout shipment lifecycle
- Real-time notifications via subscription-based push API
- Standardized event codes and change log tracking
- Unified API supporting both detailed data and change log consumption
## Important Notes
- PFC is not an invoice or legal document
- PFC should not be construed as a request for payment
- The PFC process concludes once the invoice is produced and no further updates are expected
- Monitoring begins immediately upon onboarding, including any shipments currently in flight
- Access is restricted to debtors and/or authorized agents only (including consignees when authorized)
- Data options, notification frequency, and data retention may be limited by carrier capabilities, as defined in the NMFTA PFC PRD
- Notifications are triggered by changes to shipment-level attributes that affect freight charges, including:
- Changes to the Shipper, Consignee, or Bill-To party
- Changes to the account number used for pricing
- Modifications to payment terms
- Addition or removal of accessorial charges (including waived $0 charges)
- Shipment characteristic changes that affect rating
- Customers may choose to process detailed data, change logs, or both, depending on implementation preference
version: "1.0.4"
x-prd-version: "December 2025"
contact:
name: NMFTA Digital LTL Council
email: support@nmfta.org
license:
name: NMFTA License
url: https://www.nmfta.org/license
paths:
/v1/subscriptions:
post:
summary: Subscribe to receive preliminary freight charge notifications
description: Creates a subscription to receive notifications for specified accounts, including in-flight shipments for new subscribers.
operationId: createSubscription
tags:
- Subscriptions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionRequest'
responses:
'201':
description: Subscription created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
/v1/subscriptions/{subscriptionId}:
get:
summary: Gets subscription details
description: Retrieves details of a specific subscription.
operationId: getSubscriptionDetails
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Unique identifier for the subscription
schema:
type: string
example: sub_abc123
responses:
'200':
description: Subscription details retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
summary: Cancels subscription
description: Cancels an existing subscription.
operationId: cancelSubscription
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Unique identifier for the subscription
schema:
type: string
example: sub_abc123
responses:
'204':
description: Subscription cancelled successfully
headers: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/v1/subscriptions/{subscriptionId}/inflight:
get:
summary: Gets in-flight shipments
description: Retrieves a list of in-flight shipments for a specific subscription, representing shipments in transit for subscribed accounts at the time of subscription creation.
Returns an empty array if no in-flight shipments are found for the subscription.
operationId: getInflightShipments
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Unique identifier for the subscription
schema:
type: string
example: sub_abc123
responses:
'200':
description: List of in-flight shipments
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PreliminaryFreightCharge'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/v1/preliminary-freight-charges/:
post:
summary: Post to Subscription defined endpoint PFC information
description: Post to Subscription defined endpoint PFC information.
operationId: postFreightCharges
tags:
- Preliminary Freight Charges
responses:
'200':
description: Freight charges history
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PreliminaryFreightCharge'
/webhooks/test:
post:
summary: Tests webhook endpoint
description: Tests webhook delivery for notifications.
operationId: testWebhookDelivery
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
webhookUrl:
type: string
format: uri
description: Webhook URL to test
responses:
'200':
description: Webhook test successful
'400':
$ref: '#/components/responses/BadRequest'
components:
schemas:
SubscriptionRequest:
type: object
required:
- webhookUrl
- accounts
- dataOptions
properties:
webhookUrl:
type: string
format: uri
description: URL to receive notifications
example: "https://yourapi.com/webhooks/pfc"
accounts:
type: array
items:
type: string
minItems: 1
description: List of account numbers to monitor. At least one account is required. Availability may be limited by carrier capabilities.
example: ["ACC001", "ACC002"]
dataOptions:
$ref: '#/components/schemas/DataOptions'
frequency:
type: string
enum: [real_time, hourly, daily]
default: real_time
description: Notification frequency preference. Options may be limited by carrier rating frequency.
includeEventLog:
type: boolean
default: true
description: Whether to include event change log
billScope:
type: string
enum: [all_accounts, subscribed_accounts]
default: subscribed_accounts
description: Scope of bills to include in notifications. 'all_accounts' refers to all accounts the user is authorized to access.
SubscriptionResponse:
allOf:
- $ref: '#/components/schemas/SubscriptionRequest'
- type: object
properties:
subscriptionId:
type: string
description: Unique identifier for the subscription
example: "sub_abc123"
status:
type: string
enum: [active, inactive, suspended]
description: >
Current subscription status.
- `active`: actively receiving notifications
- `inactive`: deactivated by user or system
- `suspended`: temporarily paused due to errors or system conditions
createdAt:
type: string
format: date-time
description: Subscription creation timestamp
example: "2025-06-30T10:17:34.050Z"
updatedAt:
type: string
format: date-time
description: Last update timestamp
example: "2025-06-30T10:17:34.050Z"
DataOptions:
type: object
properties:
shipmentDataType:
type: string
enum: [revenue_impacts_only, all_monitored_events]
default: revenue_impacts_only
description: Type of shipment data to include. Options may be limited by carrier capabilities.
eventType:
type: string
enum: [revenue_impacts_only, all_impacts, no_events]
default: revenue_impacts_only
description: Type of events to include. Options may be limited by carrier capabilities.
PreliminaryFreightCharge:
description: |
Submits a completed Preliminary Freight Charges (PFC) transaction to the endpoint defined by the subscription.
The payload includes shipment details, charges, references, origin/destination, and other supporting data.
The response returns a historical list of matched PFCs associated with the submission.
type: object
required:
- pfc
- payment
- shipmentTotals
- referenceNumbers
- origin
- destination
- billTo
- commodities
- charges
properties:
pfc:
type: object
required:
- uniqueID
- function
- date
- version
- isTest
properties:
uniqueID:
type: string
example: '1234567890EXLA'
description: |
Unique ID for this transaction
Concatenate PRO + SCAC + Ship date (YYYYMMDD ie 20240224), strip special characters.
header:
type: object
properties:
function:
type: string
example: 'PFC1'
description: |
The version of PFC
Valid Values: PFC1, PFC2 and so on
date:
type: string
example: '2024-11-20T00:00:00.000'
description: |
Date of the status being reported
Valid Formats:
* YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
version:
type: string
example: 'v1.0'
description: |
Indicates which minor version of the Digital LTL Council PFC spec you are consuming
Valid values: v1.0
isTest:
type: boolean
example: false
description: >-
Indicates whether or not the submitted request is intended to be
a test or not.
payment:
type: object
required:
- terms
properties:
terms:
type: string
example: Prepaid
description: |
Freight Billing Terms for the shipment
Valid Values:
* Prepaid
* Collect
* Third Party
shipmentTotals:
type: object
required:
- pickupDate
- grossWeight
- weightUnit
- handlingUnits
properties:
pickupDate:
type: string
example: '2022-11-20T00:00:00.000'
description: |
Actual ship date
Valid Formats:
* YYYY-MM-DDTHH:mm:ss.sss (ISO 8601)
grossWeight:
type: integer
example: 2000
description: >-
Total weight of the entire shipment, including handling units
(tare weight)
netWeight:
type: integer
example: 1975
description: >-
Total weight of the entire shipment, not including handling
units (tare weight)
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight
Valid Values: Pounds or Kilograms
handlingUnits:
type: integer
example: 2
description: Handling unit count for the entire shipment
linearLength:
type: integer
example: 56
description: Linear length for the entire shipment
dimensionsUnit:
type: string
example: inches
default: inches
description: |
The unit of measurement for dimensions. Defaults to Inches (Imperial) if not passed
Valid Values: Inches or Centimeters
cube:
type: integer
example: 128
description: >-
Cubic volume of the entire shipment (total length X total width
X total height).
cubeDimensionsUnit:
type: string
example: Feet
default: feet
description: |
The unit of measurement for cubic dimensions. Defaults to Feet (Imperial) if not passed.
Valid Values: Feet or Meters
declaredValue:
type: integer
example: 700
description: >-
Total monetary value of the shipment in USD (sometimes needed
for cross-border moves)
currency:
type: string
example: USD
default: USD
description: |
Optional attribute to indicate currency of declaredValue. Defaults to USD
Valid values:
* CAD
* MXN
* USD
accessorials:
type: object
properties:
codes:
type: array
description: |
An array to hold the list of services requested for the shipment
items:
type: string
example:
- LFTD
referenceNumbers:
type: object
required:
- pro
properties:
pro:
type: string
description: >-
Shipper's pre-assigned PRO number for the requested carrier.
example: '0011234567'
quoteId:
type: string
description: >-
The quote (estimate) number provided by the carrier after submitting
a rate quote request
example: E556724
shipmentId:
type: string
description: Shipment Id (SID) number for the shipment as provided by the shipper
example: SID556724
masterBol:
type: string
description: Master Bill of Lading number for the shipment as provided by the shipper
example: MBL98472578
trailerId:
type: string
description: >-
When passed, indicates that the shipment is associated to a
specific, spotted trailer as provided by the shipper
example: TID65821
manifestId:
type: string
description: >-
When passed, indicates that the shipment is associated to a
manifest that includes multiple shipments, possibly across
multiple spotted trailers. Provided by the shipper
example: M653247
bol:
type: array
items:
type: string
example:
- BL1285647
po:
type: array
items:
type: object
properties:
number:
type: string
example: '554238'
description: The Purchase Order number as provided by the shipper
pieces:
type: integer
example: 5
description: Total pieces associated with the Purchase Order as provided by the shipper
weight:
type: string
example: '150'
description: Total weight associated with the Purchase Order as provided by the shipper
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight. Defaults to Pounds (Imperial) if not passed.
Valid Values: Pounds or Kilograms
palletized:
type: boolean
example: true
description: >-
Indicates whether or not the pieces associated with the
purchase order are on a pallet/slip/skid or not as provided by the shipper
additionalShipperInfo:
type: string
example: Freight must always stay upright
description: Additional information from the shipper per line item
additionalReferences:
type: array
items:
type: object
properties:
name:
type: string
example: Customer Reference ID
description: |
Indicates the name of the reference number being provided as provided by the shipper
value:
type: string
example: CRID12345
description: >-
Additional reference number that correlates to the
additional reference name as provided by the shipper
origin:
type: object
required:
- account
- name
- address1
- city
- stateProvince
- postalCode
- country
properties:
account:
type: string
description: Company's account number/id for the origin
example: '12345'
locationId:
type: string
description: Company's location ID for the origin
example: '808'
name:
type: string
description: Company name associated with the origin location
example: Closets Closets Closets
address1:
type: string
description: Primary address line for the origin location
example: 12 S. Closets Place
address2:
type: string
description: Secondary address line for origin location
example: ste 3
city:
type: string
description: City Name for the origin location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the state/province location
example: CA
postalCode:
type: string
example: '90001'
description: >
The 5-digit (or 6-characters for Canada) zip code for the origin location
Valid formats:
* 12345-1234 (5 digits + 4 - USA)
* 12345 (5 digits - USA/MEX)
* A1A1A1 (6 characters - CAN)
* A1A1A (5 characters - CAN)
country:
type: string
example: USA
description: |
Three letter country code for the origin location
destination:
type: object
required:
- account
- name
- address1
- city
- stateProvince
- postalCode
- country
properties:
account:
type: string
description: Company's account number/id for the destination
example: '12345'
locationId:
type: string
description: Company's location ID for the destination
example: '808'
name:
type: string
description: Company name associated with the destination location
example: Closets Closets Closets
address1:
type: string
description: Primary address line for the destination location
example: 12 S. Closets Place
address2:
type: string
description: Secondary address line for destination location
example: ste 3
city:
type: string
description: City Name for the destination location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the state/province destination location
example: CA
postalCode:
type: string
example: '90001'
description: >
The 5-digit (or 6-characters for Canada) zip code for the destination location
country:
type: string
example: USA
description: |
Three letter country code for the destination location
billTo:
type: object
required:
- account
- name
- address1
- city
- stateProvince
- postalCode
- country
properties:
account:
type: string
description: Company's account number/id for the billTo
example: '12345'
locationID:
type: string
description: Company's location ID for the billTo
example: '808'
name:
type: string
description: Company name associated with the billTo location
example: Closets Closets Closets
address1:
type: string
description: Primary address line for the billTo location
example: 12 S. Closets Place
address2:
type: string
description: Secondary address line for billTo location
example: ste 3
city:
type: string
description: City Name for the billTo location
example: Los Angeles
stateProvince:
type: string
description: |
Two letter state/province code for the state/province billTo location
example: CA
postalCode:
type: string
example: '90001'
description: >
The 5-digit (or 6-characters for Canada) zip code for the billTo location
country:
type: string
example: USA
description: |
Three letter country code for the billTo location
commodities:
type: object
required:
- handlingUnits
properties:
handlingUnits:
type: array
items:
type: object
required:
- count
- type
- weight
- weightUnit
- length
- width
- height
- dimensionUnit
properties:
count:
type: integer
example: 2
description: Number of Handling units being described
type:
type: string
example: SKD
description: Type of the handling units being described
tareWeight:
type: integer
example: 5
description: Weight of the skids/pallets/slips used in the shipment
weight:
type: integer
example: 1500
description: Total weight for the specified handling units
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight
Valid Values: Pounds or Kilograms
length:
type: integer
example: 48
description: The length of the handling unit being described
width:
type: integer
example: 48
description: The width of the handling unit being described
height:
type: integer
example: 48
description: The height of the handling unit being described
dimensionUnit:
type: string
example: Inches
description: |
The unit of measurement for dimensions
Valid Values: Inches or Centimeters
stackable:
type: boolean
example: false
description: >-
Identifies whether or not the freight being described can be
stacked on one another
lineItems:
type: array
items:
type: object
required:
- description
- weight
- weightUnit
- pieces
- packagingType
- classification
properties:
description:
type: string
example: Small frameless mirrors
description: Description of the freight being described
weight:
type: integer
example: 1500
description: Total weight for the specified lineItem
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight
Valid Values: Pounds or Kilograms
pieces:
type: integer
example: 3
description: >-
Number of individual pieces for the line item being
described
packagingType:
type: string
example: box
description: >-
Packaging type for the individual pieces of the line
item being described
classification:
type: string
example: '55'
description: Classification of the line item being described
nmfc:
type: string
example: '86900'
description: NMFC of the code being described
nmfcSub:
type: string
example: '3'
description: >-
The Sub value for the NMFC of the freight being
described
charges:
type: object
required:
- grossCharges
- discountAmount
- discountPercent
- fuelSurchargePercent
- fuelSurchargeAmount
- currencyType
- preliminaryTotalCharges
properties:
grossCharges:
type: number
example: 858.55
description: Gross charges for the shipment
discountAmount:
type: number
example: 657.65
description: Amount of Discount applied to the shipment
discountPercent:
type: integer
example: 77
description: Percent of Discount applied to the shipment
totalTareWeight:
type: integer
example: 770
description: Total weight of the skids/pallets/slips used in the shipment
tareWeightAmount:
type: number
example: 50
description: Charges for Tare Weight
deficitWeight:
type: number
example: 20.63
description: Added deficit weight
fuelSurchargePercent:
type: integer
example: 31
description: Fuel Charge Percent
fuelSurchargeAmount:
type: number
example: 62.88
description: Fuel Charge Amount
currencyType:
type: string
example: USD
description: |
Attribute to indicate currency of monetary charges. Defaults to USD
Valid Values:
* CAD
* MXN
* USD
weightUnit:
type: string
example: Pounds
description: |
The unit of measurement for weight charges
Valid Values: Pounds or Kilograms
detail:
type: string
example: House/Residential Delivery Fee
description: >-
All other items in the section are standard. This line(s) would be
other charges, accessorials, etc. There can be none, one or many
preliminaryTotalCharges:
type: number
example: 263.78
description: Preliminary Charges at the time of this notification
class:
type: array
description: Array of class based charges detail
items:
type: object
properties:
freightClass:
description: >
NMFC freight class (e.g., 55 = fairly dense freight like metal parts or bottled beverages).
Standard values range from 50 to 500.
type: string
example: '55'
cwt:
type: integer
description: Cents per hundred weight
e
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nmfta/refs/heads/main/openapi/nmfta-dsdc-ltl-preliminary-freight-charges-openapi.yml