> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# AltCurrency- (Alternative currency)

> The tags for displaying prices in a second currency: switch currency and output converted product prices, basket totals, and additional costs.

A shop bills in one currency but can additionally show its prices to the visitor in a second one. That is exactly what the tags in this group do: they output prices, totals, and costs converted, without changing anything about the billing.

Which second currencies are available and which factor is used for conversion is defined in the `shop.config` in the `<AlternativeCurrency>` section.

> [!NOTE]
>
> Not all tags in this group carry the prefix `AltCurrency-`. They are spread across the prefixes `WS-`, `FORM-`, `BT-`, `PR-`, `BD-`, and `BASKET-` and are grouped here because together they form one function. Within the brackets for shipping and payment costs, there are also local tags without a prefix.

Guide: Alternative currency · Reference: AlternativeCurrency section

## Two rules that apply to almost all tags

### The currency parameter

Most tags accept a three-letter currency ISO code as a parameter. Without a parameter, they convert into the currency the visitor has currently selected. With a parameter, they convert into the specified currency, regardless of the selection.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Preis in der gewählten Währung: ~PR-AltCurrencyPrice~
Preis in Schweizer Franken:     ~PR-AltCurrencyPrice(CHE)~
```

> [!WARNING]
>
> The passed currency must be defined in the `<AlternativeCurrency>` section of the `shop.config`. If it is not, there is no conversion factor and the range remains empty.

> [!WARNING]
>
> If you output a price with a currency parameter, the parameter also belongs on the symbol. `~PR-AltCurrencyPrice(CHE)~ ~WS-AltCurrencySymbol~` writes the franc amount with the symbol of the currently selected currency. The correct form is `~PR-AltCurrencyPrice(CHE)~ ~WS-AltCurrencySymbol(CHE)~`.

### When a range applies

With ordinary price tags, the range applies if a value is present. With the AltCurrency tags, this is different: the range applies if a conversion factor exists, even if the converted amount is 0.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PR-AltCurrencyPrice}
   Preis: ~PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~
{/PR-AltCurrencyPrice}

{!PR-AltCurrencyPrice}
   Für dieses Produkt liegt kein Preis in der gewählten Währung vor.
{/!PR-AltCurrencyPrice}
```

> [!NOTE]
>
> The negative range thus answers the question "no second currency set", not "price is zero". That is the right condition for these tags, because without a conversion factor there is simply nothing to display.

## A complete example

The selection list, the price in both currencies, and the switch together:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{WS-AltCurrency}

   <form action="~FORM-AltCurrency~" method="post">
      ~WS-AltCurrencyList~
      <input type="submit" name="~BT-AltCurrency~" value="Währung wechseln">
   </form>

   <p>
      ~PR-Price~ ~WS-CurrencySymbol~
      <span>entspricht ~PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~</span>
      <span>Umrechnungsfaktor: ~WS-AltCurrencyRate~</span>
   </p>

{/WS-AltCurrency}

{!WS-AltCurrency}
   ~PR-Price~ ~WS-CurrencySymbol~
{/!WS-AltCurrency}
```

> [!WARNING]
>
> Always show both amounts and clearly mark the converted one as a conversion. Orders are placed and billed in the shop currency. If the franc amount stands alone, the visitor takes it for the invoice amount.

> [!NOTE]
>
> You only need the form `FORM-AltCurrency` if the selection list is outside of `FORM-Product` or `FORM-Basket`. If it is inside one of these two forms, the button with `BT-AltCurrency` is sufficient.

## The currency itself

| Tag | Parameter | Single tag | Range tag | Negative range tag | Permitted in |
| - | - | - | - | - | - |
| `WS-AltCurrency` | yes | yes | yes | yes | all templates |
| `WS-AltCurrencyISO` | yes | yes | yes | yes | all templates |
| `WS-AltCurrencySymbol` | yes | yes | yes | yes | all templates |
| `WS-AltCurrencyRate` | yes | yes | yes | yes | all templates |
| `WS-AltCurrencyList` | – | yes | yes | yes | product detail view, basket page |
| `FORM-AltCurrency` | – | yes | – | – | product detail view, basket page |
| `BT-AltCurrency` | – | yes | – | – | product detail view, basket page |

None of these tags can be used as a loop tag.

### WS-AltCurrency

Outputs the selected alternative currency as text. With a parameter, you check which currency is selected.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{WS-AltCurrency}

   Alternative Währung: ~WS-AltCurrency~

   {WS-AltCurrency(GBR)}
      Bereich, wenn die gewählte alternative Währung GBR ist.
   {/WS-AltCurrency(GBR)}

   {!WS-AltCurrency(GBR)}
      Bereich, wenn die gewählte alternative Währung nicht GBR ist.
   {/!WS-AltCurrency(GBR)}

{/WS-AltCurrency}

{!WS-AltCurrency}
   Es wurde keine alternative Währung gewählt.
{/!WS-AltCurrency}
```

> [!NOTE]
>
> The outer range is the most important one on this entire page. Everything related to the second currency belongs inside it. Without it, empty amounts and a lone currency symbol appear on the page as soon as no second currency is selected.

### WS-AltCurrencyISO

Outputs the three-letter ISO code of the alternative currency. With a parameter, the tag works like `WS-AltCurrency`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
ISO-Code: ~WS-AltCurrencyISO~
```

### WS-AltCurrencySymbol

Outputs the currency symbol of the alternative currency.

> [!WARNING]
>
> Place this tag after every converted amount, not `WS-CurrencySymbol`. The latter returns the symbol of the shop currency, and then a euro sign appears after the franc amount.

### WS-AltCurrencyRate

Outputs the conversion factor from the shop currency into the alternative currency.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
1 ~WS-CurrencySymbol~ entspricht ~WS-AltCurrencyRate~ ~WS-AltCurrencySymbol~
```

> [!NOTE]
>
> The factor belongs visibly on the page if you show converted prices. It makes it traceable how the second amount comes about and makes clear that it is a conversion and not a separate price.

### WS-AltCurrencyList

Outputs a ready-made selection list with all configured alternative currencies.

### FORM-AltCurrency

Returns the address for a separate form containing the selection list. It is not needed if the selection list is inside `FORM-Product` or `FORM-Basket`.

### BT-AltCurrency

Returns the name of the button used to submit the currency selection via `FORM-Product` or `FORM-Basket`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<input type="submit" name="~BT-AltCurrency~" value="Währung wechseln">
```

## Product prices

All tags in this group accept a currency ISO code and are permitted as a single tag, range tag, and negative range tag in all templates, but not as a loop tag.

| Tag | Purpose |
| - | - |
| `PR-AltCurrencyPrice` | Price, gross or net depending on the `<VAT>` section of the `shop.config` |
| `PR-AltCurrencyNetPrice` | Net price |
| `PR-AltCurrencyGrossPrice` | Gross price |
| `PR-AltCurrencyVAT` | VAT amount of the product |
| `PR-AltCurrencySetPrice` | Price of a set |
| `PR-AltCurrencyGrossSetPrice` | Gross price of a set |
| `PR-AltCurrencySetVAT` | VAT amount of a set |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PR-AltCurrencyPrice}
   ~PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~
{/PR-AltCurrencyPrice}
```

> [!NOTE]
>
> `PR-AltCurrencyPrice` follows the shop's setting; the two explicit variants do not. In a gross shop, `PR-AltCurrencyPrice` shows the same value as `PR-AltCurrencyGrossPrice`; in a net shop, the same as `PR-AltCurrencyNetPrice`. Use the explicit variant only where the value must be fixed regardless of the shop setting.

## Tiered prices

| Tag | Purpose |
| - | - |
| `BD-AltCurrencyPrice` | Tiered price |
| `BD-AltCurrencyDiscount` | Tiered price discount |

Both accept a currency ISO code, can be used as a single tag and in both range forms, and are only permitted on the product detail view (`ws_product.htm`).

Guide: Product prices, section Tiered prices

## Basket and order

These tags also accept a currency ISO code and are permitted as a single tag and in both range forms in all templates.

### Basket totals

| Tag | Purpose |
| - | - |
| `BASKET-AltCurrencySubTotalSum` | Value of goods |
| `BASKET-AltCurrencySubTotalNet` | Net value of goods |
| `BASKET-AltCurrencySubTotalGross` | Gross value of goods |
| `BASKET-AltCurrencySubTotalVAT` | VAT on the value of goods |
| `BASKET-AltCurrencyValueOfGoods` | Total value of goods of all products in the basket |
| `BASKET-AltCurrencyTotalVAT` | VAT of the entire order |
| `BASKET-AltCurrencyOrderTotal` | Final amount of the purchase |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{WS-AltCurrency}
   Endbetrag: ~BASKET-OrderTotal~ ~WS-CurrencySymbol~
   (entspricht ~BASKET-AltCurrencyOrderTotal~ ~WS-AltCurrencySymbol~)
{/WS-AltCurrency}
```

> [!WARNING]
>
> The final amount is where a second currency is most easily misunderstood. State explicitly which currency is used for billing, and put the amount in the shop currency first.

### Basket items

| Tag | Purpose |
| - | - |
| `BASKET-PR-AltCurrencyPrice` | Price per unit |
| `BASKET-PR-AltCurrencySum` | Total price of the item |
| `BASKET-PR-AltCurrencySetPrice` | Unit price of a set |
| `BASKET-PR-AltCurrencySetSum` | Total price of a set |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@BASKET-PR-Data}
   ~BASKET-PR-Name~
   ~BASKET-PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~ je Stück
   ~BASKET-PR-AltCurrencySum~ ~WS-AltCurrencySymbol~ gesamt
{/@BASKET-PR-Data}
```

## Web-to-print additional costs

For the additional costs of a web-to-print design, the same four values exist on three levels: on the product, per basket item, and as a total across the basket.

| Level | Tags |
| - | - |
| Product | `PR-AltCurrencyW2PCost()`, `PR-AltCurrencyW2PNetCost()`, `PR-AltCurrencyW2PGrossCost()`, `PR-AltCurrencyW2PVAT()` |
| Basket item | `BASKET-PR-AltCurrencyW2PCost()`, `BASKET-PR-AltCurrencyW2PNetCost()`, `BASKET-PR-AltCurrencyW2PGrossCost()`, `BASKET-PR-AltCurrencyW2PVAT()` |
| Basket total | `BASKET-AltCurrencyW2PTotal()`, `BASKET-AltCurrencyW2PTotalNet()`, `BASKET-AltCurrencyW2PTotalGross()`, `BASKET-AltCurrencyW2PTotalVAT()` |

All twelve tags can be used as a single tag and in both range forms, accept a currency ISO code, and are not loop tags. The meaning of the four variants is the same on every level: without a suffix, the value according to the shop setting; `Net` and `Gross` explicitly net or gross; `VAT` the VAT portion.

On the product:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PR-AltCurrencyW2PCost}
   Zusatzkosten für die Gestaltung: ~PR-AltCurrencyW2PCost~ ~WS-AltCurrencySymbol~
{/PR-AltCurrencyW2PCost}

{PR-AltCurrencyW2PCost(CHE)}
   Zusatzkosten in Schweizer Franken: ~PR-AltCurrencyW2PCost(CHE)~ ~WS-AltCurrencySymbol(CHE)~
{/PR-AltCurrencyW2PCost(CHE)}

{!PR-AltCurrencyW2PCost}
   Es fallen keine Zusatzkosten an.
{/!PR-AltCurrencyW2PCost}
```

Per basket item, within the item loop:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@BASKET-PR-Data}
   {BASKET-PR-AltCurrencyW2PCost}
      Zusatzkosten: ~BASKET-PR-AltCurrencyW2PCost~ ~WS-AltCurrencySymbol~
   {/BASKET-PR-AltCurrencyW2PCost}
{/@BASKET-PR-Data}
```

As a total across the basket, within the basket bracket:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BASKET-PR-Data}
   {BASKET-AltCurrencyW2PTotal}
      Gesamtkosten der Gestaltung: ~BASKET-AltCurrencyW2PTotal~ ~WS-AltCurrencySymbol~
   {/BASKET-AltCurrencyW2PTotal}
{/BASKET-PR-Data}
```

> [!NOTE]
>
> The difference between the two basket levels lies in the `@`. The item tags belong in the loop `{@BASKET-PR-Data}`, the total tags in the bracket `{BASKET-PR-Data}` without a loop.

Guide: Web-to-print products

## Local tags for shipping and payment costs

Within the display of shipping methods and chargeable additional services, separate local tags without a prefix apply. They are only available there.

| Tag | Single tag | Range tag | Negative range tag | Purpose |
| - | - | - | - | - |
| `AltCurrencyCost` | yes | yes | yes | Costs, gross or net depending on `shop.config` |
| `AltCurrencyGrossCost` | yes | – | – | Gross costs |
| `AltCurrencyNetCost` | yes | – | – | Net costs |
| `AltCurrencyISO` | yes | – | – | ISO code of the alternative currency |
| `AltCurrencySymbol` | yes | – | – | Currency symbol of the alternative currency |

In addition, the same values exist in the shop currency as `Cost`, `GrossCost`, `NetCost`, `WS-Currency`, and `WS-CurrencySymbol`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{AltCurrencyCost}
   Versandkosten: ~AltCurrencyCost~ ~AltCurrencySymbol~
{/AltCurrencyCost}

{!AltCurrencyCost}
   Versandkosten: ~Cost~ ~WS-CurrencySymbol~
{/!AltCurrencyCost}
```

> [!NOTE]
>
> `AltCurrencyCost` is the only one of these tags that can also be used as a range tag. It is therefore the switch with which you bracket the entire display in the alternative currency in or out. The other four are pure single tags and return nothing without a conversion factor.

> [!WARNING]
>
> These tags do not accept a currency parameter. They always convert into the currently selected currency.

Guide: Creating shipping methods · Guide: Creating payment methods

## Related topics

* Guide: Alternative currency
* Guide: Product prices
* Reference: AlternativeCurrency section


## Related topics

- [Web-to-print in the basket](https://dokumentation.websale.de/en/v8s/referenz/tags/basket/web-to-print-im-warenkorb.md)
- [Climate-neutral production in the basket](https://dokumentation.websale.de/en/v8s/referenz/tags/basket/klimaneutrale-produktion-im-warenkorb.md)
- [VAT rates in the basket](https://dokumentation.websale.de/en/v8s/referenz/tags/basket/mehrwertsteuersaetze.md)
- [BD- (tiered prices)](https://dokumentation.websale.de/en/v8s/referenz/tags/bd-staffelpreise.md)
- [CN- (Climate-neutral production)](https://dokumentation.websale.de/en/v8s/referenz/tags/cn.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.