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-AE",
    "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.

Spanish and Arabic market codes

Spanish and Arabic are accepted as market-specific codes only. Every Spanish code outside es-ES renders the same Spanish (Latin America) email copy, and every Arabic code renders the same Modern Standard Arabic copy; the market code selects the clock convention for that country (for example es-MX renders 3:00 PM while es-AR and es-CL render 15:00). The region-neutral tags es-419 and ar-001 are not accepted.

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.
• Links to your pages—guest email links to your site (cancellation, terms, privacy, contact, and home) carry the reservation's locale, so the guest lands on your page in the same language. The exact parameter and any tag spellings that differ on your side are set in your entity's email configuration.