openapi: 3.2.0 info: title: Nmfta Subscriptions API x-refined-note: - x-prd-version differs across the merged source definitions and was not carried version: '1.0' description: 'Operations tagged Subscriptions across 2 of this provider''s published API definitions: nmfta-dsdc-ftl-in-transit-visibility-openapi.yml, nmfta-dsdc-ltl-preliminary-freight-charges-openapi.yml. Each path carries the servers of the definition it was published in.' tags: - name: Subscriptions description: Manage webhook subscriptions paths: /v1/subscriptions: get: tags: - Subscriptions summary: List subscriptions operationId: listSubscriptions description: "Returns a page of subscriptions. Pagination in headers; body uses SubscriptionsPage for consistency.\nResults are deterministically ordered by `id`. \n" parameters: - in: query name: status schema: type: string enum: - active - paused - inactive default: active - in: query name: page schema: type: integer minimum: 1 default: 1 - in: query name: pageSize schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Subscriptions page content: application/json: schema: $ref: ./schemas/schemas.yaml#/components/schemas/SubscriptionsPage default: $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError post: tags: - Subscriptions summary: Create a subscription operationId: createSubscription description: "Create a subscription to receive in-transit events via webhook. \nProvide the delivery configuration webhook url and hmac_secret_id and filters event_types and shipment IDs. \nReturns the created Subscription on success.\n" requestBody: required: true content: application/json: schema: $ref: ./schemas/schemas.yaml#/components/schemas/SubscriptionCreate responses: '201': description: Created headers: Location: $ref: ./schemas/schemas.yaml#/components/headers/Location content: application/json: schema: $ref: ./schemas/schemas.yaml#/components/schemas/Subscription default: $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError /v1/subscriptions/{subscriptionId}: get: tags: - Subscriptions summary: Get a subscription operationId: getSubscription description: 'Retrieve a single subscription by its unique ID. Returns the subscription''s current configuration and status. ' parameters: - in: path name: subscriptionId required: true schema: type: string responses: '200': description: The subscription that matches the provided subscription ID. content: application/json: schema: $ref: ./schemas/schemas.yaml#/components/schemas/Subscription default: $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError patch: tags: - Subscriptions summary: Update a subscription (merge-patch) operationId: updateSubscription description: Partial update using [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386). Provide only fields you want to change. parameters: - in: path name: subscriptionId required: true schema: type: string requestBody: required: true content: application/merge-patch+json: schema: $ref: ./schemas/schemas.yaml#/components/schemas/SubscriptionPatch responses: '200': description: Updated subscription content: application/json: schema: $ref: ./schemas/schemas.yaml#/components/schemas/Subscription default: $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError delete: tags: - Subscriptions summary: Delete a subscription operationId: deleteSubscription description: Delete a subscription by its unique ID. Stops future deliveries and removes the subscription. parameters: - in: path name: subscriptionId required: true schema: type: string responses: '204': description: Deleted default: $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError /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' components: schemas: Error: type: object required: - code - message properties: code: type: string description: Error code message: type: string description: Human-readable error message details: type: object description: Additional error details additionalProperties: true 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\nValid formats:\n * 12345-1234 (5 digits + 4 - USA)\n * 12345 (5 digits - USA/MEX)\n * A1A1A1 (6 characters - CAN)\n * A1A1A (5 characters - CAN)\n" 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 example: 125 changeLog: type: array description: An Event is recorded for every event that had an impact for the processed day/API event items: type: object properties: eventCategoryName: type: string example: Limited Access description: Event Category Name eventCode: type: string example: LTDAD description: Standard DLC Event Code eventSubCode: type: string example: FARM description: Standard DLC Event Sub Code carrierCode: type: string example: DBRS description: Optional Carrier Event Code carrierDescription: type: string example: Debris hauled away description: Optional Carrier Event Description weightAndResearchDocAvailable: type: boolean example: false description: Indicates if a Weight and Research document is available from the Carrier for this event changeLogMessages: type: array description: Messages as apply to parent change log entry items: type: object properties: informationalMessage: type: string example: The shipment has incurred a charge for an Inside Delivery Fee description: Informational message related to the change log entry 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' 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. 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. responses: NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: NOT_FOUND message: Resource not found details: resource: proNumber value: OTPRO 999-9999999 BadRequest: description: Bad request - invalid parameters or request body content: application/json: schema: $ref: '#/components/schemas/Error' example: code: INVALID_REQUEST message: Invalid request body or parameters details: field: webhookUrl error: Must be a valid URI Forbidden: description: Access denied - insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: code: FORBIDDEN message: User not authorized as debtor or agent Conflict: description: Conflict - resource already exists or request cannot be completed content: application/json: schema: $ref: '#/components/schemas/Error' example: code: SUBSCRIPTION_CONFLICT message: A subscription for this account already exists details: accountId: '123456' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' example: code: UNAUTHORIZED message: Authentication credentials missing or invalid x-refined-from: - nmfta-dsdc-ftl-in-transit-visibility-openapi.yml - nmfta-dsdc-ltl-preliminary-freight-charges-openapi.yml