Additional Services & Charges API
API endpoints for managing additional services and charges. All endpoints require token_admin authentication.
Endpoints
| Method | Path | Description | Permission |
|---|---|---|---|
| GET | /services/{id}/additionals | List additional services or charges | plans-menu |
| POST | /services/{id}/additionals | Create additional service or charge | manage-service-config |
| PATCH | /services/{id}/additionals/{additional_id} | Update additional service or charge | manage-service-config |
GET /services/{id}/additionals
Returns additional services or charges for a service.
Path params: id (number) — Service ID
Query params:
| Param | Type | Required | Description |
|---|---|---|---|
mandatory | boolean | No | false = additional services, true = additional charges |
Response (200):
json
[
{
"id": 101,
"additional_service_id": 5,
"name": "insurance",
"operation_id": 5,
"operator": "Min + Commission (Insurance)",
"mandatory": 0,
"apply_to": "shipment",
"amount": 0.03,
"minimum_amount": 50.00,
"maximum_amount": null,
"base_amount": null,
"editable": 1,
"force_save": 0,
"active": 1,
"include_vat": 0,
"tax_percentage_included": 16,
"plan_definitions": [],
"conditions": []
},
{
"id": 102,
"additional_service_id": 8,
"name": "extended_area",
"operation_id": 4,
"operator": "Range Price Plans",
"mandatory": 1,
"apply_to": "package",
"amount": 0,
"minimum_amount": 0,
"maximum_amount": null,
"base_amount": null,
"editable": 0,
"force_save": 1,
"active": 1,
"include_vat": 0,
"tax_percentage_included": 16,
"plan_definitions": [
{
"id": 201,
"min_value": 0,
"max_value": 5,
"operation_id": 1,
"amount": 85.00,
"minimum_amount": null,
"active": 1,
"zone": null
},
{
"id": 202,
"min_value": 5,
"max_value": 30,
"operation_id": 2,
"amount": 0.15,
"minimum_amount": 85.00,
"active": 1,
"zone": null
}
],
"conditions": [
{
"id": 301,
"reference_value": "zone",
"condition": "=",
"value": 8,
"active": 1
}
]
}
]POST /services/{id}/additionals
Creates a new additional service or charge.
Request (simple operator):
json
{
"additional_service_id": 5,
"operation_id": 1,
"apply_to": "shipment",
"mandatory": 0,
"editable": 0,
"force_save": 0,
"active": 1,
"include_vat": 0,
"tax_percentage_included": 16,
"amount": 150.00,
"minimum_amount": null,
"maximum_amount": null
}Request (range-based operator with plan definitions):
json
{
"additional_service_id": 8,
"operation_id": 4,
"apply_to": "package",
"mandatory": 0,
"editable": 0,
"force_save": 0,
"active": 1,
"include_vat": 0,
"tax_percentage_included": 16,
"amount": 0,
"minimum_amount": null,
"maximum_amount": null,
"plan_definitions": [
{
"min_value": 0,
"max_value": 5,
"operation_id": 1,
"amount": 85.00,
"minimum_amount": null,
"active": 1,
"zone": null
},
{
"min_value": 5,
"max_value": 30,
"operation_id": 2,
"amount": 0.15,
"minimum_amount": 85.00,
"active": 1,
"zone": null
}
]
}Request (additional charge with conditions):
json
{
"additional_service_id": 12,
"operation_id": 1,
"apply_to": "package",
"mandatory": 1,
"editable": 0,
"force_save": 1,
"active": 1,
"include_vat": 0,
"tax_percentage_included": 16,
"amount": 200.00,
"minimum_amount": null,
"maximum_amount": null,
"conditions": [
{
"reference_value": "weight",
"condition": ">",
"value": 30,
"active": 1
},
{
"reference_value": "dimensionsSum",
"condition": ">",
"value": 300,
"active": 1
}
]
}Payload fields:
| Field | Type | Required | Description |
|---|---|---|---|
additional_service_id | number | Yes | Catalog service type ID |
operation_id | number | Yes | Operator type (1–19) |
apply_to | string | Yes | shipment, package, or unit |
mandatory | number | Yes | 0 or 1 |
editable | number | Yes | 0 or 1 |
force_save | number | Yes | 0 or 1 |
active | number | Yes | 0 or 1 |
include_vat | number | Yes | 0 or 1 |
tax_percentage_included | number | Yes | Tax rate to apply |
amount | number | Yes | Main amount (decimal for %, currency for flat) |
minimum_amount | number | No | Minimum amount (for composite operators) |
maximum_amount | number | No | Maximum cap |
plan_definitions | array | Conditional | Required for operators 4, 15, 19 |
conditions | array | Conditional | Required when mandatory = 1 |
Plan definition fields:
| Field | Type | Required | Description |
|---|---|---|---|
min_value | number | Yes | Range start (weight in kg for op 4, currency for 15/19) |
max_value | number | No | Range end (null for open-ended) |
operation_id | number | Yes | Rate type: 1 (flat), 2 (%), 3 (highest) |
amount | number | Yes | Rate value (decimal for %, currency for flat) |
minimum_amount | number | No | Flat fallback (for operation_id 3 only) |
active | number | Yes | 0 or 1 |
zone | number | No | Zone filter (optional) |
Condition fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | number | No | Existing condition ID (for updates) |
reference_value | string | Yes | Property to evaluate |
condition | string | Yes | Operator: >, >=, <, <=, =, != |
value | number | Yes | Threshold value |
active | number | Yes | 0 or 1 |
Response (201):
json
{
"id": 103,
"additional_service_id": 5,
"operation_id": 1,
"active": 1
}PATCH /services/{id}/additionals/{additional_id}
Updates an existing additional service or charge. All fields are optional (partial update). Can also be used to toggle active status only.
Toggle active only:
json
{
"active": 0
}Full update:
json
{
"operation_id": 1,
"apply_to": "package",
"mandatory": 0,
"editable": 1,
"force_save": 0,
"active": 1,
"include_vat": 1,
"tax_percentage_included": 16,
"amount": 175.00,
"minimum_amount": null,
"maximum_amount": null,
"plan_definitions": [...],
"conditions": [...]
}All payload fields are the same as POST but optional. When plan_definitions or conditions are provided, the existing records are replaced (delete + re-insert).
Common Error Responses
All errors follow the Boom format:
json
{
"statusCode": 400,
"error": "Bad Request",
"message": "Descriptive error message"
}| Status | When |
|---|---|
| 400 | Validation failed (Joi schema — e.g., invalid operator, missing plan definitions for op 4) |
| 401 | Missing or invalid JWT |
| 403 | Insufficient permissions |
| 404 | Service or additional service not found |