Create a Shipping Agency — Ship Quote API Reference

Creating an agency is the first step to adding a carrier to the rate comparison engine. Each agency record stores the routing rules, shipment capabilities, pricing supplements, and — when the carrier exposes its own HTTP API — the credentials and endpoint map needed to query it in real time.

The code field is automatically derived from name by the API (lower-cased, diacritics stripped, spaces replaced with _). It is not accepted as a request body field — the server always computes it from name.

Endpoint

POST /api/v1/agencies

Request Body

name

string

required

Human-readable agency name. Must be between 3 and 14 characters. The value is title-cased automatically (e.g. "dachser" is stored as "Dachser").

type

string

default:"static"

Determines how the rate engine sources prices for this agency. Accepted values:

Value	Description
`"static"`	Rates are read from locally stored zone and rate documents in MongoDB.
`"api"`	Rates are fetched in real time from the carrier’s external HTTP API. `apiConfig` is required.
`"hybrid"`	Both static and API sources are used. `apiConfig` is required.

rules

object

Routing and capability rules applied during rate comparison.

Show rules fields

rules.hasAndaluciaRule

boolean

default:"false"

Applies a special surcharge or alternative zone mapping for destinations in Andalusia (southern Spain). Enable only for carriers that bill this region differently.

rules.supportsPallets

boolean

default:"true"

When true, the engine includes this agency when the shipment contains pallet items.

rules.supportsParcels

boolean

default:"false"

When true, the engine includes this agency when the shipment contains parcel items.

rules.coverage

array of strings

default:"[\"national\"]"

Geographic scope this agency serves. Accepted values are "national" and "international". The engine filters agencies by comparing this field against the detected shipment scope (derived from countryCode).

["national"]
["international"]
["national", "international"]

supplements

object

Pricing supplements applied on top of the base rate.

Show supplements fields

supplements.fuelSurcharge

object

Fuel surcharge configuration added to every quoted shipment for this agency.

Show fuelSurcharge fields

supplements.fuelSurcharge.enabled

boolean

default:"false"

Toggle the fuel surcharge on or off without removing the configuration.

supplements.fuelSurcharge.type

string

default:"percentage"

How the surcharge amount is applied. "percentage" multiplies the base rate; "fixed" adds a flat euro amount.

supplements.fuelSurcharge.value

number

default:"0"

The surcharge amount. For "percentage", supply a value like 5.5 (meaning 5.5 %). For "fixed", supply the euro amount (e.g. 2.50).

apiConfig

object

Carrier API connection details. Required when type is "api" or "hybrid". Ignored for "static" agencies.

Show apiConfig fields

apiConfig.baseUrlApi

string

Base URL of the carrier’s HTTP API (e.g. "https://api.dachser.com"). Required when type is "api" or "hybrid".

apiConfig.timeout

number

default:"3000"

Maximum time in milliseconds to wait for a response from the carrier API before aborting the request. Defaults to 3 000 ms.

apiConfig.apiKey

string

Authentication key sent to the carrier API. Required when type is "api" or "hybrid".

apiConfig.endpoints

object

Carrier-specific URL paths appended to baseUrlApi for each operation.

Show endpoints fields

apiConfig.endpoints.quotations

string

Path used to request rate quotations (e.g. "/v2/quotations").

apiConfig.endpoints.transportOrders

string

Path used to create transport orders (e.g. "/v2/orders").

Response

A successful request returns HTTP 201 Created with the full agency document.

string

MongoDB ObjectId of the newly created agency.

name

string

Title-cased agency name as stored.

code

string

Normalised slug identifier derived from name.

type

string

Agency type: "static", "api", or "hybrid".

active

boolean

true if the agency is included in rate comparisons.

rules

object

Capability and routing rules as stored.

Show rules fields

hasAndaluciaRule

boolean

supportsPallets

boolean

supportsParcels

boolean

coverage

array of strings

supplements

object

Stored supplement configuration.

Show supplements.fuelSurcharge fields

fuelSurcharge.enabled

boolean

fuelSurcharge.type

string

fuelSurcharge.value

number

apiConfig

object

Carrier API configuration (present for "api" and "hybrid" agencies).

Show apiConfig fields

baseUrlApi

string

timeout

number

apiKey

string

endpoints

object

Show endpoints fields

quotations

string

transportOrders

string

createdAt

string

ISO 8601 timestamp of when the agency was created.

updatedAt

string

ISO 8601 timestamp of the last update.

Examples

The following example creates Dachser as an "api" agency that covers both national and international shipments, bills a 5.5 % fuel surcharge, and handles pallets only.

curl -X POST http://localhost:3000/api/v1/agencies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dachser",
    "type": "api",
    "rules": {
      "hasAndaluciaRule": false,
      "supportsPallets": true,
      "supportsParcels": false,
      "coverage": ["national", "international"]
    },
    "supplements": {
      "fuelSurcharge": {
        "enabled": true,
        "type": "percentage",
        "value": 5.5
      }
    },
    "apiConfig": {
      "baseUrlApi": "https://api.dachser.com",
      "timeout": 5000,
      "apiKey": "sk_live_xxxxx",
      "endpoints": {
        "quotations": "/v2/quotations",
        "transportOrders": "/v2/orders"
      }
    }
  }'

Error Responses

400 Bad Request

object

Returned when a required field is missing or a value fails Mongoose schema validation (e.g. name shorter than 3 characters, unrecognised type value, or missing baseUrlApi for an "api" agency).

{
  "message": "Name is required"
}

409 Conflict

object

Returned when an agency with the same code already exists. Agency codes are derived from name and enforced as unique by a MongoDB index.

{
  "message": "Resource duplicate"
}

Rates

Agencies

Locations

Pallets & Zones

Create a Shipping Agency — Ship Quote API Reference

Endpoint

Request Body

Response

Examples

Error Responses

Build docs developers (and LLMs) love

Rates

Agencies

Locations

Pallets & Zones

Documentation Index

​Endpoint

​Request Body

​Response

​Examples

​Error Responses

Build docs developers (and LLMs) love

Endpoint

Request Body

Response

Examples

Error Responses