> For the complete documentation index, see [llms.txt](https://docs.phptravels.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.phptravels.com/startup/setup/currencies.md). # Currencies This guide explains how the **multi-currency** system works in PHPTRAVELS: how to add currencies, set your base currency, keep exchange rates up to date manually or automatically, and how the whole thing fits together. > **Where to find it:** Admin panel → **Settings → Currencies** (`https://yourdomain.com/admin/settings/currencies`) *** ### 1. Overview Your platform can display prices in many currencies. It does this with two simple ideas: 1. **One default (base) currency** — the currency all your prices are stored in. Its exchange rate is always `1`. 2. **Exchange rates for every other currency** — a number that says *"how much 1 unit of the base currency is worth in this currency."* When a customer switches the currency on the website, the platform multiplies the base price by that currency's rate to show a converted price. **Example** — if your base currency is **USD** and the rate for **EUR** is `0.90`: ``` Price in USD (base) : 100.00 EUR rate : 0.90 Price shown in EUR : 100 × 0.90 = 90.00 ``` Keeping those rates accurate is what this feature is all about. *** ### 2. The base (default) currency Every platform has **exactly one** default currency. It is the anchor for all conversions. * Its exchange rate is always **1.00**. * All product/booking prices are stored internally in this currency. * It's marked with the **Default** toggle in the currencies table. #### Changing the default currency On the Currencies page, switch the **Default** toggle on any currency. A confirmation appears because this is a system‑wide change: * The selected currency's rate is set to **1.00** and it becomes the new base. * All **new** invoices, billing, and transactions use this currency going forward. * **Existing** transactions keep the currency values they were created with. > ⚠️ Change the default currency only when you really mean to — it affects the whole system. *** ### 3. Managing currencies On **Settings → Currencies** you can: | Action | How | | -------------------- | ------------------------------------------------------------------------------ | | **Add** a currency | Click **Create New**, enter the 3‑letter code (e.g. `EUR`), country, and rate. | | **Edit** a currency | Click the edit (pencil) icon on its row. | | **Enable / disable** | Use the **Status** toggle. Disabled currencies are hidden from the website. | | **Set default** | Use the **Default** toggle (see section 2). | | **Delete** | Click the delete icon. The default currency cannot be deleted. | **Currency code rules:** codes must be exactly **3 uppercase letters** (ISO 4217), e.g. `USD`, `EUR`, `GBP`, `AED`. *** ### 4. Exchange rates The **Rate** column is the heart of the system. You have two ways to keep it accurate. #### Option A — Update manually (one click) At the top of the Currencies page, in the **Exchange Rate API** card, click **Update Exchange Rates**. The platform will: 1. Read your **default** currency. 2. Fetch the latest rate for every other currency from the exchange‑rate provider. 3. Update the **Rate** column for all currencies. 4. Save a snapshot of this run to history (see section 7). A spinner shows while it runs; when it finishes, the page reloads with fresh rates. #### Option B — Update automatically (cron) Set up a scheduled job once and your rates stay current forever — no manual clicks. See section 6. > Both options do exactly the same work. The only difference is *who* triggers it — you, or the server on a schedule. *** ### 5. The Exchange Rate API key Rates come from [**apilayer**](https://apilayer.com/) **— Currency Data API**. You need a free (or paid) API key from them for updates to work. #### Getting a key 1. Create an account at [**apilayer.com**](https://apilayer.com/). 2. Subscribe to the **Currency Data** API (a free plan is available). 3. Copy your **API Key** from the apilayer dashboard. #### Saving the key 1. Go to **Settings → Currencies**. 2. In the **Exchange Rate API** card, paste your key into the **apilayer API Key** field. 3. Click **Update** next to the field. Your key is stored securely in the database and is used for every manual and automatic update from then on. > **Note:** The key is stored in your platform's settings — not in any configuration file — so you can change it anytime from this screen. *** ### 6. Automatic updates with a Cron Job A **cron job** is a task your server runs automatically on a schedule. Point it at the platform's currency‑update URL and your rates refresh by themselves. #### The Cron URL You'll find it ready to copy in the **Exchange Rate API** card: ``` https://yourdomain.com/update_currency_rates ``` Opening this URL (or having a scheduler open it) performs exactly the same update as the **Update Exchange Rates** button. #### Setting up the schedule On most Linux servers (cPanel, Plesk, or a raw server), add a cron entry. To update **once a day at 3:00 AM**: ```bash 0 3 * * * curl -s "https://yourdomain.com/update_currency_rates" > /dev/null 2>&1 ``` **In cPanel:** *Cron Jobs* → set the timing → paste the `curl` command above. #### Choosing how often Exchange rates don't move dramatically minute‑to‑minute, and API providers have monthly request limits. Recommended cadence: | Frequency | Cron timing | Good for | | ----------- | -------------- | ------------------------------------- | | Once a day | `0 3 * * *` | Most stores (recommended) | | Twice a day | `0 */12 * * *` | Higher‑volume stores | | Every hour | `0 * * * *` | Only if you need near‑real‑time rates | > Each currency uses one API request per update, so more currencies × more frequent updates = more requests against your apilayer quota. Daily is plenty for the vast majority of stores. *** ### 7. Update history Every update run — whether from the button or the cron — is recorded so you have a full audit trail. Each history record stores: * The **default currency** at the time of the run. * A **snapshot of every currency's rate** (as JSON). * **How many** currencies were updated. * The **date and time** of the run. This lets you see exactly what rates were applied and when — useful for reconciling prices or debugging a rate that looks off. *** ### 8. How rates are actually used When a price is shown to a customer: ``` displayed price = base price × (rate of the selected currency) ``` * The customer picks a currency (top of the website). * The platform takes the stored **base‑currency** price and multiplies by that currency's **rate**. * Any markup/tax rules are applied on top. Because everything is anchored to the base currency, you only ever maintain **one** set of prices — the rates handle the rest. *** ### 9. Step‑by‑step: first‑time setup A quick checklist to go from zero to fully automated: 1. **Set your base currency** — Settings → Currencies → turn on **Default** for your main currency. 2. **Add the currencies you want to sell in** — click **Create New** for each (e.g. EUR, GBP, AED). 3. **Get an apilayer API key** — sign up at apilayer.com, subscribe to Currency Data, copy the key. 4. **Save the key** — paste it into the **apilayer API Key** field and click **Update**. 5. **Do a first manual update** — click **Update Exchange Rates** to confirm everything works. 6. **Automate it** — copy the **Cron URL** and add a daily cron job on your server. That's it — your prices now stay converted and current automatically. *** ### 10. Troubleshooting | Symptom | Likely cause & fix | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | *"Currency API key is not configured"* | You haven't saved an apilayer key. Add it in the **Exchange Rate API** card and click **Update**. | | *"No default currency found"* | No currency is marked as default. Turn on the **Default** toggle for one currency. | | *Invalid / expired API key* | The key is wrong, expired, or your plan changed. Get a fresh key from apilayer and save it again. | | *Request limit / quota exceeded* | You've hit apilayer's monthly request cap, or your cron runs too often. Reduce frequency (daily is recommended) or upgrade your apilayer plan. | | *Some currencies didn't update* | Usually an unsupported currency code or a temporary API hiccup. Check the code is a valid 3‑letter ISO code and run the update again. | | *Rates look wrong* | Confirm the **default** currency is correct — all rates are calculated relative to it. Change the default and re‑run the update if needed. | | *Update takes a while* | Each currency is one API request, so many currencies take longer. This is normal; the cron runs in the background so it won't affect visitors. | *** ### 11. Quick reference | Item | Value | | ------------------ | ------------------------------------------------------------------ | | Currencies screen | `/admin/settings/currencies` | | Cron URL | `/update_currency_rates` | | Rate provider | apilayer — Currency Data API | | Recommended cron | `0 3 * * * curl -s "https://yourdomain.com/update_currency_rates"` | | Base currency rate | Always `1.00` | | Conversion formula | `displayed = base price × currency rate` | *** *Need help? Contact support or see the full documentation at* [*docs.phptravels.com*](https://docs.phptravels.com/)*.*