> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Variantti

> Listauksen tietty versio, joka eroaa muista attribuuteiltaan kuten koko, väri tai vuokra-aika.

<Frame caption="Katalogi > Listaukset > [Listaus] > Variantit">
  <img src="https://mintcdn.com/twicecommerce/Ab7tx7ih94KQsi0k/images/catalog-listing-variants.webp?fit=max&auto=format&n=Ab7tx7ih94KQsi0k&q=85&s=0a062eee747016a798248e34e4bede2a" alt="Varianttien määritys listauksella" width="1920" height="1080" data-path="images/catalog-listing-variants.webp" />
</Frame>

## Määritelmä

<Snippet file="definitions/fi/variant-definition.mdx" />

<Info>
  **Vertaus:** Varianttiulottuvuus on kuin valikon vaihtoehto (koko: Small / Medium / Large), ja varianttiarvo on yksittäinen valinta. Listaus, jolla on kaksi ulottuvuutta — koko × väri — kertautuu ostettavien yhdistelmien ruudukoksi.
</Info>

<Tip>
  **Erityistä TWICEssä:** Variantit ovat TWICEssä puhtaasti listauksen katalogivaihtoehtoja. Ne eivät omista varastoa suoraan. Varianttiyhdistelmän saatavuus ja keräily ratkaistaan **varianttisäännöillä**, jotka ohjaavat kunkin yhdistelmän vastaaviin varastoartikkeleihin.
</Tip>

## Missä sitä käytetään?

* **Katalogin esillepano** — myy useita kokoja tai värejä yhden listauksen alla listauksen monistamisen sijaan
* **Varianttikohtainen hinnoittelu** — veloita XL-koosta enemmän tai sovella kerrointa tiettyyn väriin
* **Varianttikohtainen keräily** — ohjaa kukin varianttiyhdistelmä eri SKU:hun tai attribuuttisuodattimeen
* **Varianttikohtainen saatavuus** — laske myytävissä oleva määrä erikseen kullekin varianttiarvojen yhdistelmälle
* **Verkkokaupan tuotesivu** — varianttivalitsimet näkyvät listaussivun [varaustyökalussa](/docs/fi/sales-channels/online-store/theme-editor/pages/listing), jossa asiakas valitsee vaihtoehtonsa päivämäärien ja määrän ohella

## Variantin rakenne

Listauksen varianttimäärityksessä on kolme kerrosta:

```
Listing
└── Variants[]            ← axes (Size, Colour, Frame …)
     ├── name             ← axis name shown on PDP
     ├── orderIndex       ← order axes appear in
     └── values[]         ← axis values (S, M, L …)
          ├── value
          └── orderIndex
```

`CatalogItemVariant` on ulottuvuus; se sisältää `CatalogItemVariantValue`-rivinsä. API:n palauttama yksittäinen ulottuvuus näyttää tältä:

```json theme={null}
{
  "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde",
  "catalogItemId": "a9b8c7d6-e5f4-4321-b098-7654321fedcb",
  "name": "Size",
  "orderIndex": 0,
  "values": [
    { "id": "11111111-1111-4111-8111-111111111111", "variantId": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "value": "S", "orderIndex": 0 },
    { "id": "22222222-2222-4222-8222-222222222222", "variantId": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "value": "M", "orderIndex": 1 },
    { "id": "33333333-3333-4333-8333-333333333333", "variantId": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "value": "L", "orderIndex": 2 }
  ]
}
```

Yksittäinen ostettava yhdistelmä on karteesinen tulo, jossa on yksi arvo kutakin ulottuvuutta kohden. Listaus, jolla on `Size = S | M | L` ja `Colour = Red | Blue`, tuottaa kuusi yhdistelmää.

## Varianttiulottuvuudet (tyypillinen käyttö)

Varianttiulottuvuudet ovat vapaamuotoisia — `name` on pelkkä merkkijono — mutta muutamat käytännöt ovat yleisiä:

| Ulottuvuus  | Tyypilliset arvot                                                                          |
| ----------- | ------------------------------------------------------------------------------------------ |
| Koko        | `XS`, `S`, `M`, `L`, `XL`                                                                  |
| Väri        | `Black`, `White`, `Red`. Admin näyttää värinäytteen, kun arvo on tulkittavissa CSS-väriksi |
| Rungon koko | `48 cm`, `52 cm`, `56 cm`                                                                  |
| Pituus      | `170 cm`, `180 cm`, `190 cm`                                                               |

Admin käyttää listauksen taksonomiakategoriaa nostaakseen esiin **suositellut attribuutit** yhden napsautuksen ulottuvuusehdotuksina, mutta skeema ei rajoita sinua niihin.

<Note>
  Vuokra-aikaa **ei** mallinneta varianttiulottuvuutena. Kesto kuuluu hintataulukoihin (varaushintarivit kentillä `timeUnit` ja `timeUnitAmount`). Käytä variantteja fyysisiin tuotevaihtoehtoihin ja hintataulukoita aikaperusteisiin hintaportaisiin.
</Note>

## Varianttikohtainen hinnoittelu

Varianttikohtainen hinnoittelu on hintataulukossa, ei itse variantissa. Kun liität hintataulukon listaukseen, jolla on variantteja, voit halutessasi lisätä `CatalogItemVariantPricingTable`-lohkon. Lohko asettaa `rateMultiplier`-kertoimen tietylle varianttiarvolle tai arvojen yhdistelmälle, ja sitä sovelletaan perushintarivien päälle.

Muutama sääntö:

* Ilman varianttikohtaista merkintää jokainen varianttiyhdistelmä käyttää perushintarivejä.
* `rateMultiplier`-arvo `1.0` vastaa perushintaa; `1.2` lisää 20 %; `0.8` antaa 20 % alennuksen.
* Varianttikohtaiset ohitukset ovat olemassa erikseen tyypeille `booking`, `sales` ja `subscription`.
* Variantit-välilehti merkitsee yhdistelmän tekstillä ”Variant pricing”, kun ohitus on olemassa, ja muuten tekstillä ”Base”.

Katso koko hinnoittelumalli kohdasta [Hintataulukko-käsite](/docs/fi/concepts/catalog/price-tables).

## Varianttikohtainen keräily (varianttisäännöt)

Listauksen keräilysäännöt kertovat tilausten reitittimelle, mitkä varastoartikkelit voivat täyttää tilauksen. Jokaisella perussäännöllä (`CatalogItemRule`) voi olla varianttiohituksia (`CatalogItemVariantRule`), jotka vaihtavat ehdot tietylle varianttiarvolle:

`CatalogItemVariantRule` sisältää seuraavat kentät:

| Kenttä           | Tyyppi     | Kuvaus                                                    |
| ---------------- | ---------- | --------------------------------------------------------- |
| `id`             | Merkkijono | Palvelimen luoma tunniste                                 |
| `variantValueId` | Merkkijono | Varianttiarvo, jota ohitus koskee                         |
| `baseRuleId`     | Merkkijono | Ohitettava peruskeräilysääntö                             |
| `conditions`     | Taulukko   | Varastoartikkelien vastaavuusehdot tälle varianttiarvolle |
| `quantity`       | Luku       | Varattavien kappaleiden määrä                             |
| `createdAt`      | Aikaleima  | Milloin sääntö luotiin                                    |

Adminissa tämä näkyy **Keräily**-välilehdellä yhtenä rivinä varianttiarvoa kohden, ja siinä näkyy perussääntö sekä mahdolliset ohittavat ehdot. Ehdot kohdistavat varastoartikkeleita attribuutin, artikkelikoodin, SKU-koodin, artikkelin nimen tai SKU:n nimen perusteella.

Esimerkki: listauksella on perussääntö ”varaa 1 kappale, joka vastaa ehtoa `category = bike`”. Lisäät varianttiulottuvuuden `Frame size` arvoilla `48`, `52`, `56`. Sitten lisäät kolme varianttisääntöä — yhden kutakin rungon kokoa kohden — joista kukin lisää ehdon `attribute:frame_size = 48 cm` (ja niin edelleen). Tämän jälkeen tilausten reititin varaa automaattisesti oikean runkokoon kappaleita.

## Varianttien saatavuus

Varianttiyhdistelmien saatavuus lasketaan katalogin päätepisteellä `GET /catalog/:id/available-by-variant-value-groups`. Jokainen pyyntö ottaa listan varianttiarvojen ryhmiä (yksi ryhmä kutakin kiinnostavaa yhdistelmää kohden) ja palauttaa pyydetyllä aikavälillä saatavilla olevien varastoartikkelien määrän kullekin ryhmälle, halutessasi palvelusijainneittain eriteltynä.

Admin niputtaa nämä pyynnöt 50 yhdistelmän ryhmiin liian suurten kyselyjen välttämiseksi.

## Varianttien SKU-koodit ja viivakoodit

Varianteilla ei ole omaa SKU-koodisaraketta listauksella. Variantin yhdistäminen varastotunnisteisiin tapahtuu näin:

1. **Varianttisäännöillä**, jotka kohdistavat suodattimia `sku_code`, `item_code` tai `attribute:*` varastoartikkeleihin.
2. **Viivakoodeilla** listauksella (`CatalogItemBarcode`), jotka ohjaavat skannatun koodin tähän listaukseen. Viivakoodit ratkaistaan tällä hetkellä listaustasolla, ei varianttiyhdistelmän tasolla.

Jos yksittäisen SKU-koodin on aina ohjattava tiettyyn varianttiyhdistelmään, koodaa tämä varianttisäännöllä, jonka ehto on `sku_code = …` ja `quantity = 1`.

## Keskeiset ominaisuudet

### Varianttiulottuvuus (`CatalogItemVariant`)

| Ominaisuus      | Tyyppi                      | Kuvaus                                                         |
| --------------- | --------------------------- | -------------------------------------------------------------- |
| `id`            | UUID                        | Palvelimen luoma                                               |
| `catalogItemId` | UUID                        | Omistava listaus                                               |
| `name`          | Merkkijono                  | Ulottuvuuden nimike (koko, väri, rungon koko ja niin edelleen) |
| `orderIndex`    | Luku                        | Näyttöjärjestys muiden ulottuvuuksien joukossa                 |
| `values`        | `CatalogItemVariantValue[]` | Tälle ulottuvuudelle määritetyt arvot                          |

### Varianttiarvo (`CatalogItemVariantValue`)

| Ominaisuus   | Tyyppi     | Kuvaus                               |
| ------------ | ---------- | ------------------------------------ |
| `id`         | UUID       | Palvelimen luoma                     |
| `variantId`  | UUID       | Omistava ulottuvuus                  |
| `value`      | Merkkijono | Näytettävä arvo                      |
| `orderIndex` | Luku       | Arvojen näyttöjärjestys tuotesivulla |

## Suhteet

<AccordionGroup>
  <Accordion title="Kuuluu listaukseen">
    Variantit ovat olemassa vain [listauksen](/docs/fi/concepts/catalog/listings) sisällä. Listauksen poistaminen poistaa kaikki sen variantit. Variantteja ei voi jakaa listausten kesken.
  </Accordion>

  <Accordion title="Varianttisäännöt viittaavat niihin">
    `CatalogItemVariantRule.variantValueId` osoittaa tiettyyn arvoon ja `baseRuleId` siihen peruskeräilysääntöön, jonka se ohittaa. Katso keräilysääntömalli kohdasta [Listaus-käsite](/docs/fi/concepts/catalog/listings).
  </Accordion>

  <Accordion title="Varianttikohtaiset hintarivit viittaavat niihin">
    Varianttikohtaiset hinnoitteluohitukset viittaavat varianttiarvoihin kentän `CatalogItemVariantPricingTable.values` kautta. Katso [Hintataulukko-käsite](/docs/fi/concepts/catalog/price-tables).
  </Accordion>

  <Accordion title="Kohdistuu SKU:ihin ja varastoartikkeleihin">
    Varianttiyhdistelmä ei osoita SKU:hun suoraan. Polku on: varianttiarvo → varianttisäännön ehdot → vastaavat [varastoartikkelit](/docs/fi/concepts/inventory/stock-items) tilaushetkellä.
  </Accordion>
</AccordionGroup>

## Elinkaari

<Steps>
  <Step title="Ulottuvuuden lisäys">
    `POST /variants/:catalogItemId` arvoilla `{ name, values? }`. Arvot voi luoda tässä tai myöhemmin kutsulla `POST /variants/:catalogItemId/values/:variantId`.

    <AccordionGroup>
      <Accordion title="Voinko lisätä toisen ulottuvuuden, kun ensimmäinen on jo käytössä?">
        Kyllä. Olemassa olevat varianttisäännöt ja varianttikohtainen hinnoittelu pysyvät kiinni niissä arvotunnisteissa, joilla ne luotiin — ne eivät laajene automaattisesti uusiin yhdistelmiin, mikä sallii uusien ulottuvuuksien käyttöönoton rikkomatta olemassa olevaa määritystä.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Hinnoittelun määritys">
    Liitä hintataulukko Hinnoittelu-välilehdellä. Lisää halutessasi `CatalogItemVariantPricingTable`-merkintöjä, jotka ohittavat perushinnan tietyillä varianttiarvoilla.
  </Step>

  <Step title="Keräilyn määritys">
    Lisää perussääntö Keräily-välilehdellä. Lisää jokaiselle varianttiarvolle, jonka keräily poikkeaa, varianttisääntö mukautetuin ehdoin ja määrin.
  </Step>

  <Step title="Järjestäminen">
    `POST /variants/:catalogItemId/reorder` taulukolla `variantIds` muuttaa ulottuvuuksien järjestystä. Arvojen järjestys päivitetään kutsulla `PUT /variants/:catalogItemId/:variantId`.
  </Step>

  <Step title="Arvojen muokkaus">
    `PUT /variants/:catalogItemId/:variantId` arvoilla `{ name, values }` nimeää ulottuvuuden uudelleen ja muokkaa sen arvoja. Kutsusta pois jätetyt arvot poistetaan Adminin lomakkeen `deleteValues`-päätepisteellä.
  </Step>

  <Step title="Poisto">
    `DELETE /variants/:catalogItemId/:variantId` poistaa ulottuvuuden. Sen arvoihin sidottuja varianttisääntöjä tai varianttikohtaista hinnoittelua ei enää sovelleta.
  </Step>
</Steps>

## Usein kysytyt kysymykset

<AccordionGroup>
  <Accordion title="Mikä ero on varianttiarvolla ja SKU:lla?">
    Varianttiarvo (`Size = M`) on katalogin ulottuvuuden nimike. SKU on varastomäärittely. Samaa varianttiarvoa voi palvella moni SKU sen mukaan, millaisia varianttisääntöjä ja ehtoja määrität.
  </Accordion>

  <Accordion title="Voiko kaksi listausta jakaa variantteja?">
    Ei. Variantit kuuluvat yhteen listaukseen. Jos kaksi listausta tarvitsee samat ulottuvuudet, luo ne kummallekin erikseen — mutta harkitse, voisiko listaukset yhdistää.
  </Accordion>

  <Accordion title="Miten estän tietyn koon ylimyynnin?">
    Varmista, että jokaisella varianttiarvolla on varianttisääntö, jossa `quantity = 1` (tai enemmän) ja ehdot, jotka kohdistuvat oikeisiin varastoartikkeleihin. Kyseisen varianttiyhdistelmän myytävissä oleva määrä huomioi tällöin vain vastaavat kappaleet.
  </Accordion>

  <Accordion title="Mihin kesto sijoitetaan, jos ei varianttina?">
    Kesto määritetään hintataulukon varaushintariveinä (esimerkiksi `1 päivä 40 €`, `3 päivää 100 €`, `1 viikko 180 €`). Asiakas valitsee keston [varaustyökalussa](/docs/fi/sales-channels/online-store/theme-editor/pages/listing); varianttivalitsin hoitaa vain fyysiset vaihtoehdot.
  </Accordion>

  <Accordion title="Miten hinnoittelen värin 20 % perushintaa kalliimmaksi?">
    Lisää hintataulukkoon kyseiselle väriarvolle varianttikohtainen hinnoittelumerkintä arvolla `rateMultiplier = 1.2`.
  </Accordion>
</AccordionGroup>

## Kehittäjän viite

Listausten variantit näkyvät API:ssa nimellä `variants`.

<Card title="API: Variants" icon="code" href="https://server.twicecommerce.com/api/internal">
  Avaa päätepiste API-referenssissä.
</Card>

## Aiheeseen liittyvää

<CardGroup cols={2}>
  <Card title="Listaukset" icon="list" href="/docs/fi/concepts/catalog/listings">
    Katalogin rivi, johon variantit kuuluvat
  </Card>

  <Card title="Hintataulukot" icon="table" href="/docs/fi/concepts/catalog/price-tables">
    Missä varianttikohtaiset hinnoitteluohitukset määritetään
  </Card>

  <Card title="SKU:t" icon="barcode" href="/docs/fi/concepts/inventory/skus">
    Varastomäärittelyt, joista variantti toimitetaan
  </Card>

  <Card title="Varastoartikkelit" icon="box" href="/docs/fi/concepts/inventory/stock-items">
    Fyysiset kappaleet, jotka varataan varianttiyhdistelmää kohden
  </Card>
</CardGroup>