The Avvail API uses explicit locale tags to determine the language of transactional communications (confirmation, reminder, and cancellation emails) sent to guests. Locale is never inferred from country, market, or any other geographic field.

How Locale Resolution Works

When creating a reservation via POST /v2/reservations, you may include an optional locale field. If omitted, the server falls back to the entity's default_locale. If the entity has no default_locale configured, en-US is used.

reservation.locale → entity.default_locale → en-US

Once set on a reservation, the locale is immutable and cannot be changed via PATCH /v2/reservations/{id}.

Configuring Entity Defaults

Each entity can have a default_locale set via POST /v2/entities or PATCH /v2/entities/{id}. This is useful when an entity (distribution channel) primarily serves a single-language market.

curl -X PATCH https://api.avvail.com/v2/entities/7f3c2b1a-8e4d-4f9c-a6b2-3d5e1a7c9f2b \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_locale": "fr-FR"}'

Setting Locale on a Reservation

Pass locale in the reservation creation request to override the entity default:

curl -X POST https://api.avvail.com/v2/reservations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "option_id": "opt_abc123xyz",
    "locale": "ar-001",
    "guest": {
      "first_name": "Nadia",
      "last_name": "Hassan",
      "email": "nadia.hassan@example.com",
      "mobile_number": "+971555555555"
    }
  }'

The resolved locale is returned in the reservation response as a read-only field.

Supported Locale Codes

All values are BCP 47-style tags. The locale and default_locale fields accept only the values listed below.

Providing an unsupported value returns 400 Bad Request with a validation error.

Key Points

• locale controls transactional email language only — it does not affect API response content or error messages
• locale is separate from country and market — a guest in France may receive emails in English, and vice versa
• locale is immutable on a reservation once created
• Entities without an explicit default_locale default to en-US

What Gets Localized

When a reservation is persisted with a non-en-US locale, the following surfaces render in the guest's language:

• Email body copy — all transactional copy in guest-facing emails sent for the reservation.
• Email subject line — e.g. "Votre réservation au Le Bistro est confirmée !" for fr-FR.
• Date and time formatting inside the body — month and day-of-week names, component order, and 12- vs 24-hour clock all follow the locale's conventions.