Carriers and quotations

A carrier is a company that moves goods for you, for example a courier or a freight company. A quotation is the price and the service level that one carrier offers for one shipment. Cargopilot asks each configured carrier for a quotation, and shows all the quotations on the shipment. You accept one of them.

The carrier catalogue

Miridia keeps a catalogue of carriers. Send GET /api/carriers to read it. Add ?configured=true to read only the carriers that your business uses.

Each carrier in the catalogue lists what it can do:

• the fulfilment types and sub-types, for example Package or StandardEuroPallet
• the service levels, for example Express or SameDay
• the delivery types, for example DoorToDoor or DoorToCollectionPoint
• the requirements, for example a signature on delivery

Configure a carrier

Configure a carrier one time for each business.

1. In the portal, open Fulfillment Settings. To find it, search for it in the command palette.
2. Add the carrier, and fill in the values that it needs, for example an account number.
3. Select a contact at the carrier, if you have one.
4. Save the configuration.

The same page holds the service level templates and the carrier contacts.

With the API, send POST /api/carriers/configure with the carrierId and the configuredValues. Set defaultOption to true for the carrier that you use most. To change the options of a configured carrier, send PATCH /api/carriers/{carrierId}. To remove it, send DELETE /api/carriers/{carrierId}.

Keep the contacts at each carrier with /api/carriers/contacts, for example an account manager or a depot.

The quotation loop

Cargopilot gets the quotations in the background. Thus the shipment is ready at once, and the quotations arrive some seconds later.

1. You create a shipment. Miridia raises the OnShipmentCreated event.
2. Miridia sends the shipment to the connector of each configured carrier.
3. Each connector asks its carrier for a price.
4. Each connector sends one quotation for each rate to POST /api/v1/integration/shipments/quotations.
5. The quotations show on the shipment. Miridia raises the OnShipmentQuotationGenerated event.

The business configuration AutoGenerateShipmentQuotation controls step 2. It is on by default. Turn it off if you do not want quotations for each new shipment.

A quotation holds the carrier, the service level, the sub-total, the tax, the discount, the total price, the currency, and the collection and delivery dates that the carrier offers.

The carrier connectors return live rates from the API of each carrier. For a carrier that Miridia does not connect yet, build your own connector, for example in n8n. Read Build a connector.

Read and accept a quotation

A shipment has a maximum of one accepted quotation. When you accept a quotation, Cargopilot resets each other accepted quotation of that shipment. The carrier of the accepted quotation becomes the carrier of the shipment. Miridia raises the OnShipmentQuotationAccepted event, and the business gets a notification.

You cannot delete the accepted quotation. Withdraw the acceptance first.

Ask the carriers again

A price can become old, or the shipment can change. Send POST /api/v1/shipments/{shipmentId}/quotations/refresh to get new prices. Cargopilot deletes the quotations that are not accepted, and asks each carrier again. The new quotations arrive through the same loop. Thus the response holds the shipment, not the quotations.

The request fails with status 409 in these two conditions:

• A quotation of the shipment is accepted. Withdraw the acceptance first.
• The shipment cannot change its quotations any more, for example because it left the Active status.

Booking

When you accept a quotation, Cargopilot books the shipment with the carrier. It stores the tracking number of the carrier in trackingId, and the carrier label on the shipment. Read Waybills and labels. To add your own steps to the booking, attach a workflow to OnShipmentQuotationAccepted.

Build a carrier connector

A carrier connector receives the GenerateShipmentQuotation request, and replies with a 2xx status at once. Then it gets the prices and sends each one to the callback. Read Build a connector for the full contract.

The request from Miridia holds the shipment in the body, and these headers:

Send the callback with the same x-miridia-api-key value. Do not store the key. Each request has a new key.

{
  "quotation": {
    "providerId": 4,
    "shipmentId": "<shipment-id>",
    "serviceLevelText": "Overnight",
    "serviceLevelDescription": "Delivery on the next working day",
    "fulfillmentType": "Package",
    "currency": "ZAR",
    "subTotal": 120.00,
    "totalTax": 18.00,
    "totalPrice": 138.00,
    "taxIncluded": true
  },
  "context": {
    "configuredProviderId": "<configured-provider-id>",
    "id": "<carrier-quote-reference>",
    "idType": "String"
  }
}

API reference

• Carriers
• Shipments
• Shipment integration