Workspace Pricing Configuration

Retrieve the active pricing configuration for your workspace. This includes base rates, tiered rates for distance and weight, city-specific overrides, and insurance surcharges.

---

Endpoint

GET/v1/workspace/pricing

Required permission: workspace:price

---

Response

Pricing Object

Field	Type	Description
intraCity	Object	Pricing rules for deliveries within the same city.
weight	Object	Tiered pricing rules based on package weight.
valueSurcharge	Object	Insurance surcharge rules based on the declared value of shipments.

Intra-City Pricing (intraCity)

Field	Type	Description
base	Integer	Flat base rate in ₦ for intra-city shipments.
distanceTiers	Array	Array of distance tiers defining rates per kilometer.

Each element in distanceTiers contains:

• maxKm (Integer): Maximum distance in kilometers for this tier.
• ratePerKm (Integer): The rate charged per kilometer in ₦.

Weight Pricing (weight)

Field	Type	Description
base	Integer	Flat base rate in ₦ for weight-based tiers.
weightTiers	Array	Array of weight categories defining rates and limits.

Each element in weightTiers contains:

• id (String): Unique identifier for the tier.
• name (String): Display name of the weight tier.
• description (String): Description of what packages fit into this tier.
• maxKg (Integer): Maximum package weight in kilograms for this tier.
• rate (Integer): Surcharge rate in ₦ applied to shipments in this tier.

Value Surcharge (valueSurcharge)

Field	Type	Description
base	Integer	Flat base rate in ₦ for value-based insurance.
valueTiers	Object	Configuration of percentage fees when insurance is enabled.

The valueTiers object contains:

• enabled (Boolean): Whether value surcharge / insurance is active.
• percentageFee (Float): The percentage of declared item value charged as insurance fee (e.g., 1.5 represents 1.5%).

---

Weight Category Integration Flow

When creating shipments via the API, you need to provide a packageCategory (e.g. SMALL, MEDIUM). Instead of hardcoding these tiers, you should dynamically retrieve them from this pricing endpoint:

1. Fetch Active Categories: Call GET /v1/workspace/pricing to retrieve the current list of weightTiers.
2. User Selection: Render the available options (using the tier name and description) for your users to select.
3. Submit Shipment: Pass the selected tier's id as the packageCategory parameter in the POST /v1/shipments payload.

tip

Hiding Active Pricing from End Users: If you do not want your customers to see the underlying pricing rates (e.g., base fares, km rates, or surcharges), you should call GET /v1/workspace/pricing on your secure backend server, extract only the category fields (id, name, description, maxKg), and send only this filtered list to your frontend.

---

{
"statusCode": 200,
"message": "Success",
"data": {
  "intraCity": {
    "base": 1000,
    "distanceTiers": [
      {
        "maxKm": 99999999,
        "ratePerKm": 200
      }
    ],
  },
  "weight": {
    "base": 0,
    "weightTiers": [
      {
        "id": "SMALL",
        "name": "Small",
        "description": "Fits in a shoebox (e.g., Documents, Keys, Phones) - Up to 3kg",
        "maxKg": 3,
        "rate": 500
      },
      {
        "id": "MEDIUM",
        "name": "Medium",
        "description": "Fits in a backpack (e.g., Clothes, Laptops) - Up to 10kg",
        "maxKg": 10,
        "rate": 800
      },
      {
        "id": "LARGE",
        "name": "Large",
        "description": "Requires two hands to carry (e.g., Microwaves, multiple boxes) - Up to 25kg",
        "maxKg": 25,
        "rate": 3000
      },
      {
        "id": "EXTRA_LARGE",
        "name": "Extra Large",
        "description": "Requires a Van/Truck (e.g., Furniture, Wholesale) - 25kg+",
        "maxKg": 999999,
        "rate": 5000
      }
    ]
  },
  "valueSurcharge": {
    "base": 0,
    "valueTiers": {
      "enabled": false,
      "percentageFee": 1.5
    }
  }
}
}