Integration Guide For Carriers
Integration Guide For Carriers

Fundamentals

This guide provides carriers with an overview of the key integration points and workflows when connecting with MachShip. Each integration point has detailed guides available for implementation specifics.

Authentication & Credentials

MachShip can handle credentials at different levels depending on how your system is structured:

  • Carrier-Level Credentials: A single set of SFTP or API credentials used across all customer accounts with your carrier
  • Account-Level Credentials: Individual credentials for each customer account, provided per account when required
  • Carrier Account Details: Customer account numbers and related details can be included in all API requests or file transfers

We work with your existing authentication model – whether that’s a single API integration, per-account credentials, or a hybrid approach.

Key Integration Points

The following sections outline the typical integration workflow. Not all integration points are required – we’ll work with you to determine which apply to your system.

1. Routing & Pricing (Optional)

MachShip can manage pricing and validation in several ways, and these can be combined based on your system capabilities:

  • MachShip-Managed Rate Cards: You provide your pricing structure and we load it into MachShip. Pricing is calculated internally without calling your system.
  • API-Based Pricing: If you have a pricing API, we can integrate with it to get real-time quotes for each shipment.
  • Hybrid Approach: It’s common to use API calls for validation (address validation, timeslot availability, dispatch date validation) while pricing is calculated using rate cards loaded in MachShip. This provides real-time validation without requiring pricing API calls.

Additional validation capabilities that can be integrated via API:

  • Address validation – confirming delivery addresses are serviceable
  • Service availability – checking if specific services are available for a route
  • Item restrictions – validating size, weight, or item type constraints
  • Account validation – confirming customer account details are correct
  • Timeslot validation – checking available delivery windows
  • Dispatch date validation – confirming pickup date feasibility

Even when pricing is managed internally, basic service zones and coverage areas are configured in MachShip to determine which carriers are presented as options.

2. Consignment Creation

When a customer creates a consignment in MachShip, we need to pass that information to your system. Key considerations:

Data Transfer Timing

  • At Manifest (Typical): For most carriers, we don’t send consignment data until the customer manifests (finalizes) the shipment. This allows them to edit consignments before they’re locked in.
  • At Creation (When Required): If your system needs to generate consignment IDs or item references, or if you need data for load planning, we can send data at creation time.
  • Generic Integrations: Typically only send data at manifest stage to maintain maximum flexibility.

Consignment IDs & Barcodes

  • MachShip-Generated: We can generate consignment IDs and item barcodes using your preferred prefix and numbering format
  • Carrier-Generated: Your system can generate these identifiers and return them to MachShip when the consignment is created or manifested

MachShip’s preference is to generate these identifiers when possible, as it provides more flexibility for customers to edit consignments before finalization.

Consignment Editing

  • Editing Supported: If your system allows consignments to be modified or cancelled before pickup, we can send edit/cancel requests
  • Editing Not Supported: If consignments are final once created, we’ll hold data in MachShip until manifest to give customers editing capability on our side

3. Labelling

MachShip handles label generation in several ways:

  • MachShip-Built Labels: We build consignment labels to your specifications. You provide the label layout, required fields, barcode formats, and any carrier-specific requirements. Labels are generated by MachShip when the consignment is created.
  • Carrier-Generated Labels: Your system generates labels and provides them to MachShip via API or file transfer.
  • Generic Label: For carriers with flexible requirements, MachShip offers a standard 10x15cm label format that includes essential shipping information and scannable barcodes.

All label formats require carrier approval before being used in production.

4. Manifesting & Pickups

Manifesting is when customers finalize a group of consignments and request a pickup:

  • Manifest Data: Contains consignment details, item references, pickup address, requested pickup time, and any special instructions
  • Bulk or Individual: Some carriers need one manifest per pickup, others need individual bookings per consignment – we handle both
  • Pickup Booking: May be combined with manifest or a separate request, depending on your system requirements

For generic integrations, this is typically when consignment data is first transmitted to your system.

5. Tracking & Status Updates

MachShip needs to receive status updates as consignments move through your network. Several options are available:

  • Webhook: Your system pushes status events to a MachShip endpoint in real-time
  • API Polling: MachShip polls your API on a schedule to retrieve status updates
  • File-Based (FTP/SFTP): Status updates are provided in files (CSV, XML, JSON) on a regular schedule
  • Carrier API (Generic Integrations): For generic integrations, you can POST status updates directly to MachShip’s Carrier API

Status events are standardized in MachShip so customers see consistent tracking information across all carriers.

6. Proof of Delivery (PODs)

When a consignment is delivered, MachShip captures proof of delivery:

  • With Status Updates: POD images or documents can be included in delivery status events
  • Separate Upload: PODs can be uploaded separately after delivery
  • Supported Formats: Images (JPG, PNG) or PDF documents

Integration Methods

MachShip supports several technical integration approaches:

  • REST/SOAP APIs: Real-time data exchange via web services
  • File Transfer (FTP/SFTP): Batch processing via CSV, XML, or JSON files
  • Email: For basic integrations, data can be exchanged via email
  • Hybrid: Combination of methods (e.g., API for booking, files for tracking)

References & Identifiers

Understanding the different identifiers used in carrier integrations:

  • Consignment ID (MachShip): Unique identifier in MachShip’s system
  • Carrier Consignment ID: Your system’s unique identifier for the shipment (e.g., ABC000123)
  • Item Reference: Barcode/identifier for each package in the shipment
  • Customer References: Customer’s order/invoice numbers (up to 2 per consignment)
  • Account Number: The customer’s account number with your carrier

Common Questions

Do we need to implement all integration points?
No. We work with your existing capabilities. Some carriers only provide basic file-based consignment data, while others offer full API integration with real-time pricing and tracking.

How long does integration take?
It depends on the integration type and your system capabilities. We’ll provide a timeline estimate once we understand your technical requirements.

Can we use our existing label format?
Yes, if you already generate labels. Otherwise, we can build labels to your specifications or you can use our generic format.

What if we need to change our integration later?
Integrations can be updated as your systems evolve. We’ll work with you to implement changes with minimal disruption to existing customers.

Who handles customer support?
MachShip handles first-line support for consignment creation and tracking questions. Carrier-specific operational issues (e.g., delivery delays, damaged goods) are escalated to your support team.

Support

For integration assistance, contact MachShip carrier support via our carrier integrations form here.

© 2026 MachShip Documentation