Skip to content

Package Mappings Endpoints

Location: backend/service_multi-repricer/app/api/v1/endpoints/package_mappings.py

Purpose

Manage mappings from weight ranges (in grams) to shipping package types and costs. These mappings are used by shipping cost calculations and repricer workflows that need package cost estimations.

Primary fields (returned by endpoints)

  • id (int)
  • min_weight (Decimal) — minimum weight inclusive (grams)
  • max_weight (Decimal | null) — maximum weight inclusive (grams); null means no upper bound
  • package_type (string)
  • cost (Decimal) — cost in EUR
  • created_at, updated_at (ISO datetime)

Endpoints

  • GET / — List all mappings

  • Returns all mappings ordered by min_weight.

  • POST / — Create a new mapping

  • Request JSON (PackageMappingCreate): { "min_weight": Decimal, "max_weight": Decimal | null, "package_type": str, "cost": Decimal }
  • Validations:
    • If max_weight provided, min_weight < max_weight.
    • Rejects creation when the new range overlaps any existing mapping (server-side overlap check).

  • Response: {"status": "success", "mapping_id": <id>} (201-like semantics)

  • PUT /{mapping_id} — Update existing mapping

  • Accepts partial updates via PackageMappingUpdate.
  • When changing min/max weights the endpoint validates the updated range does not overlap other mappings and min < max (if max provided).

  • Response: {"status": "success", "mapping_id": <id>}

  • DELETE /{mapping_id} — Delete mapping

  • Removes the mapping row and returns {"status": "success", "mapping_id": <id>}

  • GET /find_by_weight/{weight} — Find mapping that contains the given weight

  • Path: weight (float, grams)
  • Logic: returns the mapping where min_weight <= weight and (max_weight IS NULL OR max_weight >= weight); chooses the mapping with the highest min_weight when multiple matches exist.
  • Response: { "package_type": str, "cost": float, "weight_range": {"min_weight": float, "max_weight": float | null} }

Examples

  • Create mapping (curl):
curl -X POST "http://localhost:8000/api/v1/multi/" \
  -H "Content-Type: application/json" \
  -d '{"min_weight": 0.00, "max_weight": 1000.00, "package_type": "small_box", "cost": 2.50}'
  • Find mapping for 750g:
curl "http://localhost:8000/api/v1/multi/find_by_weight/750"

Operational notes

  • Units: weights are grams and stored as DECIMAL(10,2); use floats or decimals in requests but prefer Decimal when constructing programmatic requests.
  • Overlap checks are performed at application level; concurrent writes may still cause race conditions — consider DB-level constraints or application-level locks if collisions are observed under high concurrency.
  • max_weight being null represents an "infinite" upper bound. Creation or update that sets overlapping ranges against an existing null upper bound will be rejected.

Package Mappings Endpoints

Router prefix: /package_mappings → full base: /api/v1/multi/package_mappings

Summary: CRUD and lookup endpoints for package mappings (weight/size → package code).

Implementation: backend/service_multi-repricer/app/api/v1/endpoints/package_mappings.py

TODO: Populate detailed method table and examples.