Chargeable weight (beta)

Work out the weight a carrier bills: the greater of actual and volumetric weight.

weight.chargeable Beta call

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/weight/chargeable

{
    "type": "object",
    "properties": {
        "divisor": {
            "type": [
                "number",
                "null"
            ],
            "maximum": 100000,
            "exclusiveMinimum": 0
        },
        "divisor_unit": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "cm3_kg",
                "in3_lb"
            ]
        },
        "increment": {
            "type": [
                "number",
                "null"
            ],
            "maximum": 100,
            "exclusiveMinimum": 0
        },
        "packages": {
            "type": "array",
            "minItems": 1,
            "maxItems": 1000,
            "items": {
                "type": "object",
                "properties": {
                    "dimension_unit": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "mm",
                            "cm",
                            "m",
                            "in"
                        ]
                    },
                    "height": {
                        "type": "number",
                        "minimum": 0
                    },
                    "id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 128
                    },
                    "length": {
                        "type": "number",
                        "minimum": 0
                    },
                    "quantity": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "minimum": 1,
                        "maximum": 100000
                    },
                    "weight": {
                        "type": "number",
                        "minimum": 0
                    },
                    "weight_unit": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "g",
                            "kg",
                            "oz",
                            "lb"
                        ]
                    },
                    "width": {
                        "type": "number",
                        "minimum": 0
                    }
                },
                "required": [
                    "height",
                    "length",
                    "weight",
                    "width"
                ]
            }
        },
        "weight_unit": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "kg",
                "lb"
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "packages"
    ]
}

Request example

{
    "packages": [
        {
            "id": "box-1",
            "weight": 2.4,
            "weight_unit": "kg",
            "length": 40,
            "width": 30,
            "height": 30,
            "dimension_unit": "cm"
        },
        {
            "id": "box-2",
            "quantity": 2,
            "weight": 9,
            "weight_unit": "kg",
            "length": 30,
            "width": 20,
            "height": 15,
            "dimension_unit": "cm"
        }
    ],
    "divisor": 5000,
    "divisor_unit": "cm3_kg",
    "increment": 0.5
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/weight/chargeable

Response schema

{
    "description": "The chargeable weight of every package and of the shipment. Billed one call.",
    "data": {
        "type": "object",
        "properties": {
            "weight_unit": {
                "type": "string",
                "enum": [
                    "kg",
                    "lb"
                ],
                "description": "The unit of every weight in the answer."
            },
            "divisor": {
                "type": "number",
                "description": "The divisor used."
            },
            "divisor_unit": {
                "type": "string",
                "enum": [
                    "cm3_kg",
                    "in3_lb"
                ],
                "description": "The divisor's unit."
            },
            "packages": {
                "type": "array",
                "description": "Every package, in the order given; weights are for one package.",
                "items": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "string",
                            "description": "The package id, or its number from 1."
                        },
                        "quantity": {
                            "type": "integer",
                            "description": "How many such packages."
                        },
                        "actual_weight": {
                            "type": "number",
                            "description": "Its weight, in `weight_unit`."
                        },
                        "volumetric_weight": {
                            "type": "number",
                            "description": "Its volume divided by the divisor, in `weight_unit`."
                        },
                        "chargeable_weight": {
                            "type": "number",
                            "description": "The greater of the two, rounded up to `increment` when given."
                        },
                        "basis": {
                            "type": "string",
                            "enum": [
                                "actual",
                                "volumetric"
                            ],
                            "description": "Which weight decided."
                        }
                    }
                }
            },
            "totals": {
                "type": "object",
                "properties": {
                    "packages": {
                        "type": "integer",
                        "description": "Packages counted with their quantities."
                    },
                    "actual_weight": {
                        "type": "number",
                        "description": "Sum of actual weights."
                    },
                    "volumetric_weight": {
                        "type": "number",
                        "description": "Sum of volumetric weights."
                    },
                    "chargeable_weight": {
                        "type": "number",
                        "description": "Sum of each package's chargeable weight: billed package by package."
                    },
                    "shipment_chargeable_weight": {
                        "type": "number",
                        "description": "The greater of the summed actual and volumetric weights: the shipment billed as one."
                    }
                }
            }
        },
        "required": [
            "weight_unit",
            "packages",
            "totals"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "weight.chargeable",
    "billing": {
        "unit": "call",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "weight_unit": "kg",
        "divisor": 5000,
        "divisor_unit": "cm3_kg",
        "packages": [
            {
                "id": "box-1",
                "quantity": 1,
                "actual_weight": 2.4,
                "volumetric_weight": 7.2,
                "chargeable_weight": 7.5,
                "basis": "volumetric"
            },
            {
                "id": "box-2",
                "quantity": 2,
                "actual_weight": 9,
                "volumetric_weight": 1.8,
                "chargeable_weight": 9,
                "basis": "actual"
            }
        ],
        "totals": {
            "packages": 3,
            "actual_weight": 20.4,
            "volumetric_weight": 10.8,
            "chargeable_weight": 25.5,
            "shipment_chargeable_weight": 20.5
        }
    },
    "meta": {
        "cm3_per_kg": 5000,
        "increment": 0.5
    }
}

What it costs

One call, whatever its size.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return