Pricing & Age Groups

Complete guide for price calculations, age categories, and discounts.

---

Overview

The LosCenotes pricing system supports:

• Age-based pricing with 5 categories and configurable multipliers
• Included and optional services
• Transportation calculations with distance-based pricing
• Automatic discounts based on user eligibility
• Coupon codes

---

Age Categories

GET /age-configurations

List all global age configurations.

curl -X GET "https://service-gateway.loscenotes.com/age-configurations" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: es"

Response:

{
  "success": true,
  "message": "age_configurations.list_retrieved_successfully",
  "data": [
    {
      "id": "uuid-infant",
      "category": "infant",
      "displayNames": {
        "es": "Bebés",
        "en": "Infants"
      },
      "descriptions": {
        "es": "Niños de 0 a 2 años",
        "en": "Children from 0 to 2 years old"
      },
      "minAge": 0,
      "maxAge": 2,
      "pricingMultiplier": 0.0,
      "isActive": true,
      "displayOrder": 1
    },
    {
      "id": "uuid-child",
      "category": "child",
      "displayNames": {
        "es": "Niños",
        "en": "Children"
      },
      "descriptions": {
        "es": "Niños de 3 a 12 años",
        "en": "Children from 3 to 12 years old"
      },
      "minAge": 3,
      "maxAge": 12,
      "pricingMultiplier": 0.8,
      "isActive": true,
      "displayOrder": 2
    },
    {
      "id": "uuid-teen",
      "category": "teen",
      "displayNames": {
        "es": "Adolescentes",
        "en": "Teens"
      },
      "descriptions": {
        "es": "Jóvenes de 13 a 17 años",
        "en": "Youth from 13 to 17 years old"
      },
      "minAge": 13,
      "maxAge": 17,
      "pricingMultiplier": 0.9,
      "isActive": true,
      "displayOrder": 3
    },
    {
      "id": "uuid-adult",
      "category": "adult",
      "displayNames": {
        "es": "Adultos",
        "en": "Adults"
      },
      "descriptions": {
        "es": "Adultos de 18 a 64 años",
        "en": "Adults from 18 to 64 years old"
      },
      "minAge": 18,
      "maxAge": 64,
      "pricingMultiplier": 1.0,
      "isActive": true,
      "displayOrder": 4
    },
    {
      "id": "uuid-senior",
      "category": "senior",
      "displayNames": {
        "es": "Adultos Mayores",
        "en": "Seniors"
      },
      "descriptions": {
        "es": "Adultos de 65 años o más",
        "en": "Adults 65 years or older"
      },
      "minAge": 65,
      "maxAge": null,
      "pricingMultiplier": 0.85,
      "isActive": true,
      "displayOrder": 5
    }
  ]
}

Default Multipliers

Category	Age Range	Multiplier	Discount
infant	0-2 years	0.0	100% (FREE)
child	3-12 years	0.8	20%
teen	13-17 years	0.9	10%
adult	18-64 years	1.0	0% (full price)
senior	65+ years	0.85	15%

---

GET /age-configurations/cenote/:cenoteId

Get age configurations specific to a cenote (may override global defaults).

curl -X GET "https://service-gateway.loscenotes.com/age-configurations/cenote/cenote-uuid" \
  -H "Content-Type: application/json"

---

GET /age-configurations/tour/:tourId

Get age configurations specific to a tour.

curl -X GET "https://service-gateway.loscenotes.com/age-configurations/tour/tour-uuid" \
  -H "Content-Type: application/json"

---

Price Calculation

POST /pricing/calculate-complete

⭐ Main endpoint for complete price calculation

This endpoint calculates the total price including:

• Age-based adjustments
• Included and optional services
• Transportation costs
• Automatic discounts
• Coupon codes

Request:

curl -X POST "https://service-gateway.loscenotes.com/pricing/calculate-complete" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_your_api_key" \
  -d '{
    "itemType": "cenote",
    "itemId": "cenote-uuid-here",
    "ageBreakdown": {
      "infant": 0,
      "child": 2,
      "teen": 1,
      "adult": 2,
      "senior": 0
    },
    "selectedServices": ["service-uuid-1", "service-uuid-2"],
    "transportationType": "hotel_pickup",
    "pickupLocation": "Hotel Xcaret",
    "pickupLatitude": 20.4567,
    "pickupLongitude": -87.1234,
    "couponCode": "VERANO2025",
    "currency": "MXN",
    "language": "es"
  }'

Request Fields:

Field	Type	Required	Description
itemType	string	✅	"cenote" or "tour"
itemId	UUID	✅	Cenote or Tour ID
ageBreakdown	object	✅	Visitor count by age category
selectedServices	array	❌	Optional service IDs
transportationType	string	❌	"meeting_point", "hotel_pickup", "private_transfer"
pickupLocation	string	❌	Hotel or pickup location name
pickupLatitude	number	❌	Pickup latitude
pickupLongitude	number	❌	Pickup longitude
couponCode	string	❌	Discount coupon code
currency	string	❌	Display currency (MXN, USD)
language	string	❌	Response language (es, en, fr)
skipTransportValidation	boolean	❌	Skip transport validation for progressive pricing

Response:

{
  "success": true,
  "message": "Cálculo de precio completado exitosamente",
  "data": {
    "basePrice": 35000,
    "ageAdjustments": {
      "infant": {
        "quantity": 0,
        "multiplier": 0,
        "subtotal": 0
      },
      "child": {
        "quantity": 2,
        "multiplier": 0.8,
        "subtotal": 56000
      },
      "teen": {
        "quantity": 1,
        "multiplier": 0.9,
        "subtotal": 31500
      },
      "adult": {
        "quantity": 2,
        "multiplier": 1.0,
        "subtotal": 70000
      },
      "senior": {
        "quantity": 0,
        "multiplier": 0.85,
        "subtotal": 0
      },
      "total": 157500
    },
    "transportationCost": {
      "type": "hotel_pickup",
      "strategy": "calculated",
      "baseCost": 15000,
      "groupDiscount": 0,
      "total": 15000,
      "pickupLocation": "Hotel Xcaret"
    },
    "services": {
      "included": [
        {
          "id": "service-included-1",
          "name": "Chaleco salvavidas",
          "cost": 0,
          "reason": "Included in package",
          "isTransport": false,
          "category": "equipment"
        }
      ],
      "selected": [
        {
          "id": "service-uuid-1",
          "name": "Equipo de snorkel",
          "cost": 5000,
          "isTransport": false,
          "category": "equipment"
        }
      ],
      "totalServicesCost": 5000
    },
    "discounts": {
      "automatic": [
        {
          "id": "discount-1",
          "name": "Descuento de temporada baja",
          "type": "percentage",
          "amount": 15750
        }
      ],
      "coupon": {
        "code": "VERANO2025",
        "type": "percentage",
        "amount": 10000
      }
    },
    "summary": {
      "subtotal": 177500,
      "discounts": 25750,
      "taxes": 0,
      "total": 151750,
      "currency": "MXN"
    }
  },
  "currency": {
    "code": "MXN",
    "symbol": "$"
  }
}

⚠️ Important: All prices are in CENTS (centavos). Divide by 100 for display.

Example: 35000 = $350.00 MXN

---

GET /pricing/summary/:itemType/:itemId

Quick pricing summary for a cenote or tour.

curl -X GET "https://service-gateway.loscenotes.com/pricing/summary/cenote/cenote-uuid?people=4" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "message": "pricing.summary_retrieved_successfully",
  "data": {
    "itemId": "cenote-uuid",
    "itemType": "cenote",
    "itemName": "Cenote Dos Ojos",
    "basePrice": 35000,
    "total": 140000,
    "currency": "MXN"
  }
}

---

POST /pricing/validate-age-breakdown

Validate an age breakdown configuration before calculating.

curl -X POST "https://service-gateway.loscenotes.com/pricing/validate-age-breakdown" \
  -H "Content-Type: application/json" \
  -d '{
    "infant": 0,
    "child": 2,
    "teen": 1,
    "adult": 2,
    "senior": 0
  }'

Response:

{
  "success": true,
  "message": "pricing.age_breakdown_valid",
  "data": {
    "isValid": true,
    "totalPeople": 5,
    "breakdown": [
      { "category": "infant", "count": 0 },
      { "category": "child", "count": 2 },
      { "category": "teen", "count": 1 },
      { "category": "adult", "count": 2 },
      { "category": "senior", "count": 0 }
    ]
  }
}

---

POST /pricing/calculate-transportation

Calculate transportation cost by distance.

curl -X POST "https://service-gateway.loscenotes.com/pricing/calculate-transportation" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "transport-service-uuid",
    "distance": 45,
    "totalPeople": 4
  }'

---

Price Calculation Example

Scenario

• Cenote base price: $350.00 MXN (35000 cents)
• Visitors: 2 adults, 2 children, 1 teen

Calculation

Category	Count	Multiplier	Unit Price	Subtotal
Adult	2	1.0	35000	70000
Child	2	0.8	28000	56000
Teen	1	0.9	31500	31500
Total	5			157500

Total: $1,575.00 MXN (157500 cents)

---

Transportation Types

Type	Description
meeting_point	Guest meets at designated location
hotel_pickup	Pickup from hotel (requires coordinates)
private_transfer	Private vehicle transfer

---

Error Codes

Code	Message	Description
CENOTE_NOT_FOUND	error.cenote.not_found	Cenote ID not found
TOUR_NOT_FOUND	error.tour.not_found	Tour ID not found
INVALID_ITEM_TYPE	error.pricing.invalid_item_type	Must be "cenote" or "tour"
PICKUP_REQUIRED	error.transport.pickup_required_when_included	Pickup info required when transport is included