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

# Peruuta kotitestipakkauksen tilaus

> Peruuta kotiin postitettava kotitestipakkaus

Peruuta kotitestipakkauksen tilaus asettamalla sen tilaksi `cancelled`. Peruutettu kotitestipakkauksen tilaus palautetaan vastauksessa.

Vain `pending`-tilassa olevan tilauksen voi peruuttaa. Kun tilaus on tilassa `dispatched`, logistiikkakumppani on jo pakannut ja merkinnyt pakkauksen, ja peruuttaminen palauttaa tilakoodin `409` — samoin kuin `activated`-tilassa olevan tilauksen kohdalla.

Jos pakkaus on jo tilattu logistiikkakumppanilta, peruutamme sen ensin siellä ennen tilauksesi peruuttamista, ja kutsu epäonnistuu, jos se ei ota sitä takaisin: `409`, kun pakkaus on jo pakattu ja merkitty, `502`, kun logistiikkakumppani hylkäsi peruutuksen tai siihen ei saatu yhteyttä. Jokaisessa virhetilanteessa **mitään ei muuteta** — tilaus pysyy voimassa, ja `502`-virheen jälkeen voit turvallisesti yrittää uudelleen.

Jo `cancelled`-tilassa olevan tilauksen peruuttaminen palauttaa tilakoodin `200` ja kyseisen tilauksen riippumatta siitä, mistä tilasta se peruutettiin. Vastaus sisältää otsikon `Idempotent-Replayed: true`, jotta voit erottaa toistokutsun varsinaisen työn tehneestä kutsusta. Katso [Idempotenssi](https://docs.anivahealth.com/fi/concepts/idempotency.md).

Vaatii `home_kit_orders_manage`-laajuuden.

## Pyyntö

### Polkuparametrit

**id** `string` *required*

Peruutettavan kotitestipakkauksen tilauksen yksilöllinen tunniste (UUID).

## Vastaus

Onnistuessaan API palauttaa tilakoodin `200 OK` sekä peruutetun kotitestipakkauksen tilauksen ja siihen upotetun profiilin. Jo aiemmin peruutettu tilaus palauttaa saman `200`-vastauksen.

**id** `string` *required*

Kotitestipakkauksen tilauksen yksilöllinen tunniste (UUID).

**profile\_id** `string` *required*

Sen profiilin UUID, jolle tämä kotitestipakkauksen tilaus kuuluu.

**status** `string` *required*

Kotitestipakkauksen tilauksen tila. On `cancelled` onnistuneen peruutuksen jälkeen.

**delivery\_address** `object` *required*

Osoite, johon pakkaus postitetaan — toinen kahdesta muodosta: joko `{ location_id }`, joka viittaa tunnettuun testipaikkaan, tai suorat osoitekentät (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` valinnaisia — sama sanasto kuin locations-API:ssa). Anna täsmälleen toinen — sijaintiviittaus tai suora osoite, ei molempia.

**toimitusosoite**

> [tab] Sijaintiviittaus
>
> **location\_id** `string` *required*
>
> Sen testipaikan UUID, johon pakkaus lähetetään.

> [tab] Suora osoite
>
> **name** `string` *required*
>
> Vastaanottajan, yrityksen tai sijainnin nimi.
>
> **company\_name** `string`
>
> Yritys, joka ottaa paketin vastaan vastaanottajan puolesta — `c/o`-taho tai osasto.
>
> **street** `string` *required*
>
> Kadunnimi ilman talon numeroa (esim. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Talon numero (esim. `118` tai `12a`).
>
> **address\_line\_2** `string`
>
> Rakennus, sisäänkäynti tai kerros.
>
> **city** `string` *required*
>
> **state** `string`
>
> Osavaltio tai maakunta. Valinnainen.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2 -koodi (kaksi kirjainta, esim. `DE`).
>
> **phone** `string`
>
> **email** `string`

**lab\_code** `string`

Laboratorion näytekoodi, jonka alla tulokset raportoidaan — painettu fyysiseen pakkaukseen, ja sen
potilas lukee rasiasta aktivointikoodina. `null`, kunnes pakkaus on pakattu.
Vain luku.

**activated\_at** `string` *required*

[Aktivoi](https://docs.anivahealth.com/fi/api/home-kit-orders/activate-home-kit.md)-päätepisteen kautta ilmoitettu näytteenoton aikaleima — ajankohta, jolloin
potilas otti näytteensä. `null`, kunnes pakkaus on aktivoitu.

**replaces\_home\_kit\_order\_id** `string`

Kotitestipakkauksen tilaus, jonka tämä tilaus korvaa, kun kyseessä on korvaava pakkaus. `null` normaalissa tilauksessa. Katso
[Luo kotitestipakkauksen tilaus](https://docs.anivahealth.com/fi/api/home-kit-orders/create-home-kit.md).

**replacement\_reason** `string`

Syy korvaavan pakkauksen lähettämiselle. `null` normaalissa tilauksessa.

**results\_ready\_emails** `string[]` *required*

Osoitteet pienillä kirjaimilla, joista jokainen saa yhden sähköpostin kaikkien laboratoriotulosten
valmistuttua. Tyhjä, kun toiminto on pois päältä. Katso
[Tulokset valmiit -sähköpostit](https://docs.anivahealth.com/fi/concepts/results.md#saehkoepostit-tulosten-valmistumisesta).

**metadata** `object` *required*

Kumppanin määrittämät avain-arvoparit, jotka palautetaan sellaisinaan. Aina mukana — `{}` kun arvoja ei ole asetettu.

**created\_at** `string` *required*

ISO 8601 -aikaleima siitä, milloin kotitestipakkauksen tilaus luotiin.

**updated\_at** `string`

ISO 8601 -aikaleima viimeisimmästä päivityksestä. Voi olla `null`.

**profile** `object` *required*

Tähän kotitestipakkauksen tilaukseen liittyvä potilasprofiili.

**profiili**

**id** `string`

Profiilin yksilöllinen tunniste (UUID).

**handle** `string`

Profiilin nimimerkki tai käyttäjätunnus. Voi olla `null`.

**first\_name** `string`

Etunimi. Voi olla `null`.

**last\_name** `string`

Sukunimi. Voi olla `null`.

**email** `string`

Sähköpostiosoite. Voi olla `null`.

**phone** `string`

Puhelinnumero E.164-muodossa. Voi olla `null`.

**sex** `integer`

Biologinen sukupuoli standardin ISO/IEC 5218 mukaisesti. Voi olla `null`.

**date\_of\_birth** `string`

Syntymäaika muodossa `YYYY-MM-DD`. Voi olla `null`.

**height** `number`

Pituus senttimetreinä. Voi olla `null`.

**weight** `number`

Paino kilogrammoina. Voi olla `null`.

**language** `string`

Ensisijainen kieli: yksi 32 koodista sivulla [Luo profiili](https://docs.anivahealth.com/fi/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Saako tämä profiili tapahtumapohjaisia (automaattisia) sähköposteja. Voi olla `null`.

**created\_at** `string`

ISO 8601 -aikaleima profiilin luontihetkestä.

**updated\_at** `string`

ISO 8601 -aikaleima profiilin viimeisimmästä päivityksestä. Voi olla `null`.

**panels** `HomeKitOrderPanel[]` *required*

Paneeli, joka oli liitetty tähän kotitestipakkauksen tilaukseen ennen peruutusta — aina täsmälleen yksi
(kotitestipakkaus vastaa 1:1 fyysistä pakkaustuotetta). Hae paneelin tiedot (nimi, biomarkkerit) käyttämällä
[Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md) -päätepistettä.

**Paneelin liittämiskentät**

**panel\_id** `string`

Paneelin UUID — tarkista vastaavuus [Listaa paneelit](https://docs.anivahealth.com/fi/api/panels/list-panels.md) -päätepisteestä.

**added\_at** `string`

ISO 8601 -aikaleima siitä, milloin paneeli liitettiin ensimmäisen kerran tähän kotitestipakkauksen tilaukseen.

**individual\_biomarkers** `HomeKitOrderIndividualBiomarker[]` *required*

Yksittäiset biomarkkerit, jotka oli liitetty tähän kotitestipakkauksen tilaukseen ennen peruutusta. Hae näyttötiedot
kullekin `biomarker_id`-arvolle [Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) -päätepisteestä parametrilla `home_kit=true`.

**Yksittäisen biomarkkerin kentät**

**biomarker\_id** `integer`

Biomarkkerin tunniste — tarkista vastaavuus
[Listaa biomarkkerit](https://docs.anivahealth.com/fi/api/biomarkers/list-biomarkers.md) -päätepisteestä parametrilla `home_kit=true`.

**added\_at** `string`

ISO 8601 -aikaleima siitä, milloin biomarkkeri liitettiin ensimmäisen kerran tähän kotitestipakkauksen tilaukseen.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Paketit, jotka oli linkitetty tähän kotitestipakkauksen tilaukseen ennen peruutusta, vanhin linkitys ensin. Lue
pakettien täydet tiedot käyttämällä [Listaa lähetykset](https://docs.anivahealth.com/fi/api/shipments/list-shipments.md) -päätepistettä ja parametria `?home_kit_order_id=`.

**Lähetyslinkityksen kentät**

**id** `string`

Lähetysviite — tarkista vastaavuus [Hae lähetys](https://docs.anivahealth.com/fi/api/shipments/get-shipment.md) -päätepisteestä.

**added\_at** `string`

ISO 8601 -aikaleima siitä, milloin lähetys linkitettiin tähän kotitestipakkauksen tilaukseen.

## Virhevastaukset

| Tila | Kuvaus |
| - | - |
| `400` | Virheellinen tunnistemuoto — annettu arvo ei ole kelvollinen UUID. |
| `403` | Pääsy estetty — API-avaimellasi ei ole oikeutta tähän toimintoon tai kotitestipakkauksen tilaus on käyttöoikeuslaajuutesi ulkopuolella. |
| `404` | Kotitestipakkauksen tilausta ei löytynyt. |
| `409` | Ristiriita — tilaus ei ole enää tilassa `pending` (lähetetty tai aktivoitu), tai logistiikkakumppani on jo pakannut ja merkinnyt sen pakkauksen. |
| `500` | Sisäinen palvelinvirhe. |
| `502` | Logistiikkakumppani hylkäsi peruutuksen (sisältää sen perustelun) tai siihen ei saatu yhteyttä. Mitään ei muutettu; tilaus on edelleen voimassa. |

```bash cURL theme={null}
curl --request DELETE \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "cancelled",
  "delivery_address": {
    "name": "Maria Schmidt",
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-03T10:00:00Z",
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": {},
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```

```json 409 theme={null}
{
  "error": "A home kit order can only be cancelled while it is pending. Once it is dispatched or activated the physical kit has been packed and labelled and can no longer be called back."
}
```

```json 502 theme={null}
{
  "error": "Fulfilment refused the cancellation (Order is already in fulfillment). The home kit order was NOT cancelled."
}
```


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