Service Configuration API

API endpoints for the Service Configuration module. All endpoints require token_admin authentication and are prefixed with /services/{id}.

Authentication

All endpoints require a valid JWT token:

Authorization: Bearer <token>

Endpoint Summary

Method	Path	Description	Permission
GET	/services/{id}/data	Get service details	plans-menu
GET	/services/{id}/taxes	Get tax rules for the service locale	plans-menu
GET	/services/{id}/costs	Get cost matrix	plans-menu
PUT	/services/{id}/costs	Update cost matrix	manage-service-costs
GET	/services/{id}/price	Get pricing matrix (all tariff types)	plans-menu
PUT	/services/{id}/price	Update pricing for one tariff type	manage-service-pricing
PATCH	/services/{id}/volumetric-factor	Update volumetric factor	manage-service-config
GET	/services/{id}/default-rates	Get default tariff per zone	plans-menu
PUT	/services/{id}/default-rates	Update default tariffs per zone	manage-service-config
GET	/services/{id}/additionals	List additional services/charges	plans-menu
POST	/services/{id}/additionals	Create additional service/charge	manage-service-config
PATCH	/services/{id}/additionals/{additional_id}	Update additional service/charge	manage-service-config

---

Service Details

GET /services/{id}/data

Returns service metadata including carrier, locale, status, and volumetric factor.

Path params: id (number) — Service ID

Response (200):

{
  "id": 42,
  "carrier": "FedEx",
  "service_code": "FEDEX_EXPRESS",
  "locale_id": 1,
  "active": 1,
  "volumetric_factor": {
    "id": 3,
    "factor": 5000,
    "unit_weight": "KG"
  }
}

---

Taxes

GET /services/{id}/taxes

Returns tax rules for the service's locale. Read-only — taxes are managed in Organization Settings.

Response (200):

{
  "tax_rules": [
    {
      "id": 1,
      "country_name": "Mexico",
      "rule_description": "Standard VAT",
      "concept_description": "IVA",
      "application_type": "transferred",
      "amount": 16,
      "default_tax": 1
    }
  ]
}

---

Volumetric Factor

PATCH /services/{id}/volumetric-factor

Updates the volumetric factor for a service by assigning a factor from the catalog.

Request:

{
  "factor_id": 3
}

Payload fields:

Field	Type	Required	Description
factor_id	number	Yes	ID from catalog_volumetric_factors

Response (200):

{
  "volumetric_factor": {
    "id": 3,
    "factor": 5000,
    "unit_weight": "KG"
  }
}

---

Default Rates

GET /services/{id}/default-rates

Returns the default tariff type assigned to each zone for the service.

Response (200):

[
  { "zone": "1", "type_id": 1, "service_id": 42 },
  { "zone": "2", "type_id": 2, "service_id": 42 },
  { "zone": "3", "type_id": null, "service_id": 42 }
]

type_id values: 1 = basic, 2 = pro, 3 = enterprise, 4 = corporate, null = no tariff assigned.

PUT /services/{id}/default-rates

Updates the default tariff type for each zone.

Request:

[
  { "zone": 1, "type_id": 1 },
  { "zone": 2, "type_id": 2 },
  { "zone": 3, "type_id": 3 }
]

Payload fields (per item):

Field	Type	Required	Description
zone	number	Yes	Zone identifier (min: 1)
type_id	number	Yes	Tariff type ID (1–4)

---

Common Error Responses

All errors follow the Boom format:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Descriptive error message"
}

Status	When
400	Validation failed (Joi schema)
401	Missing or invalid JWT
403	Insufficient permissions
404	Service not found

---

For cost/price matrix endpoints, see Pricing & Costs API.

For additional services/charges endpoints, see Additional Services API.