API Reference

Consignment Charges

Manage charges associated with consignments including activity charges, freight charges, and adhoc charges.

Endpoints Overview

Method Endpoint Description
GET /v1/consignments/{consignmentId}/charges Get consignment charges
POST /v1/consignments/{consignmentId}/charges/client-activity/adhoc Create Client Activity adhoc charge
POST /v1/consignments/{consignmentId}/charges/client-freight/adhoc Create Client Freight adhoc charge
POST /v1/consignments/{consignmentId}/charges/carrier-freight/adhoc Create Carrier Freight adhoc charge
PUT /v1/consignments/{consignmentId}/charges/{consignmentChargeId} Toggle to include/exclude charge

Get Consignment Charges

Retrieve all charges associated with a consignment.

Endpoint: GET /v1/consignments/{consignmentId}/charges

Path Parameters

Parameter Type Required Description
consignmentId uuid Yes The consignment ID

Request Example 

curl -X GET "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/charges" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response Example 

{
  "clientActivityCharges": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "isEffective": true,
      "particulars": "Storage - 7 days",
      "chargeTypeCode": "STOR",
      "chargeTypeName": "Storage",
      "metricValue": 7,
      "chargeMin": 10.00,
      "chargeBase": 0,
      "chargeRate": 5.00,
      "taxRatePercent": 15,
      "amountExclTax": 35.00
    }
  ],
  "clientFreightCharges": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440101",
      "type": 4,
      "isEffective": true,
      "particulars": "Freight to Wellington",
      "metricValue": 500,
      "chargeMin": 50.00,
      "chargeBase": 20.00,
      "chargeRate": 0.15,
      "amountExclTax": 95.00
    }
  ],
  "carrierFreightCharges": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440102",
      "type": 7,
      "isEffective": true,
      "particulars": "Carrier freight charge",
      "metricValue": 500,
      "chargeMin": 40.00,
      "chargeBase": 15.00,
      "chargeRate": 0.12,
      "amountExclTax": 75.00
    }
  ]
}

Activity Charge Fields

Field Type Description
id uuid Charge ID
isEffective boolean Whether charge is active on consignment
particulars string Charge description
chargeTypeCode string Charge type code
chargeTypeName string Charge type name
metricValue number Quantity/metric used for calculation
chargeMin number Minimum charge amount
chargeBase number Base charge amount
chargeRate number Rate per unit
taxRatePercent number Tax rate percentage
amountExclTax number Total amount excluding tax

Freight Charge Fields

Field Type Description
id uuid Charge ID
type integer Charge type (see Charge Type Values)
isEffective boolean Whether charge is active on consignment
particulars string Charge description
metricValue number Quantity/metric used for calculation
chargeMin number Minimum charge amount
chargeBase number Base charge amount
chargeRate number Rate per unit
amountExclTax number Total amount excluding tax

Charge Type Values

Value Type Description
1 ClientActivityAdhoc Client adhoc activity charge
2 ClientActivityMetricRate Client activity charge based on metric
3 ClientActivityProductRate Client activity charge based on product
4 ClientFreightAdhoc Client adhoc freight charge
5 ClientFreightMetricRate Client freight charge based on metric
6 ClientFreightProductRate Client freight charge based on product
7 CarrierFreightAdhoc Carrier adhoc freight charge
8 CarrierFreightMetricRate Carrier freight charge based on metric
9 CarrierFreightProductRate Carrier freight charge based on product

Create Adhoc Charge

Add a one-off Client Activity/Client Freight/Carrier Freight charge to a consignment.

Endpoint: POST /v1/consignments/{consignmentId}/charges/client-activity/adhoc Endpoint: POST /v1/consignments/{consignmentId}/charges/client-freight/adhoc Endpoint: POST /v1/consignments/{consignmentId}/charges/carrier-freight/adhoc

Path Parameters

Parameter Type Required Description
consignmentId uuid Yes The consignment ID

Request Body 

{
  "particulars": "Special handling fee",
  "revenueAccountId": "550e8400-e29b-41d4-a716-446655440200",
  "costCentreId": "550e8400-e29b-41d4-a716-446655440201",
  "metricValue": 1,
  "chargeApplication": 2,
  "chargeRateExclTax": 45.00,
  "taxRateId": "550e8400-e29b-41d4-a716-446655440202"
}

Request Body Fields

Field Type Required Description
particulars string No Charge description
revenueAccountId uuid No Revenue account ID
costCentreId uuid No Cost centre ID
metricValue number Yes Quantity (use 1 for fee-based)
chargeApplication integer Yes 1 = Rate, 2 = Fee
chargeRateExclTax number Yes Rate or fee amount excl. tax
taxRateId uuid Yes Tax rate ID

Charge Application Values

Value Type Description
1 Rate Amount = metricValue × chargeRateExclTax
2 Fee Amount = chargeRateExclTax (metricValue defaults to 1)

Request Example 

curl -X POST "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/charges/client-activity/adhoc" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "particulars": "Special handling fee",
    "metricValue": 1,
    "chargeApplication": 2,
    "chargeRateExclTax": 45.00,
    "taxRateId": "550e8400-e29b-41d4-a716-446655440202"
  }'

Response Example

Status: 200 OK

{
  "consignmentChargeId": "550e8400-e29b-41d4-a716-446655440300"
}

Error Cases

Status Cause Resolution
400 Invalid request body Check required fields
404 Consignment not found Verify consignment ID
404 Tax rate not found Verify tax rate ID

Update Charge

Update an existing charge's inclusion status.

Endpoint: PUT /v1/consignments/{consignmentId}/charges/{consignmentChargeId}

Path Parameters

Parameter Type Required Description
consignmentId uuid Yes The consignment ID
consignmentChargeId uuid Yes The charge ID

Request Body 

{
  "isIncluded": true
}
Field Type Required Description
isIncluded boolean Yes Whether charge should be included

Request Example 

curl -X PUT "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/charges/550e8400-e29b-41d4-a716-446655440100" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isIncluded": false}'

Response

Status Description
200 Charge updated successfully
304 Not modified (no changes)

Related Endpoints

Previous
Consignments
Next
Consignment Consumables