# REST API: objednávky, vratky a zásilky

> Referenční popis cest pro objednávky, vratky a zásilky: parametry dotazu, pole odpovědi, synchronizace přes updated_since, chyby a ukázka volání.

- Sekce: Pro vývojáře
- Stránka: https://shopzi.cz/dokumentace/vyvojari/rest-objednavky
- Ověřeno: 2026-09-16

---

Pro účetnictví, ERP a expedici: kdo co objednal, v jakém je to stavu, kolik to stálo, co se vrací a kde je zásilka.

Cesty odpovídají na `GET` na doméně vašeho obchodu, například `https://muj-eshop.cz/api/v1/…`, a klíč se posílá v hlavičce `Authorization: Bearer` nebo `x-api-key`. Parametry, pole i chyby na téhle stránce se generují ze smlouvy, podle které API odpovídá, takže platí pro build, na kterém stránka běží. Každá cesta může navíc vrátit chyby společné všem cestám: `invalid_api_key`, `missing_api_key`, `external_access_disabled`, `external_access_not_enabled`, `external_access_suspended`, `key_surface_mismatch`, `plan_required`, `shop_unavailable`, `shop_not_found`, `rate_limited` a `server_error`. Co znamenají, popisuje článek [Chybové odpovědi](/dokumentace/vyvojari/chybove-odpovedi), klíč a oprávnění [Autentizace a oprávnění](/dokumentace/vyvojari/autentizace-a-opravneni) a průchod výpisem [Stránkování a filtry](/dokumentace/vyvojari/strankovani-a-filtry).

## `GET /api/v1/orders` [#get-api-v1-orders]

Objednávky s částkami v haléřích, bez updated\_since od nejnovější, s ním od nejstarší změny. Nákupní ceny, marže, interní poznámky ani identifikátory platby ven nejdou.

* **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“.
* **Odpověď:** stránka výpisu, záznamy jsou v `data` a jak otevřít další stránku, říká seznam Obálka odpovědi.
* **Synchronizace:** s `updated_since` se výpis řadí podle pole `updated_at` od nejstarší změny, bez něj od nejnovějšího záznamu. Pole `updated_at`: Poslední změna záznamu objednávky. Podle něj stránkuje `updated_since`.

```bash
curl -s "https://muj-eshop.cz/api/v1/orders?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"
```

**Parametry dotazu**

* `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
* `cursor` (text; nepovinný): Hodnota `next_cursor` z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
* `updated_since` (čas ISO 8601; nepovinný): ISO 8601 se zónou `Z` nebo s číselným posunem (`+02:00`). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota `next_updated_since` jde do adresy vložit bez kódování; `+` z nezakódované adresy se čte jako `+`.
* `status` (jedna z hodnot `pending`, `received`, `confirmed`, `processing`, `shipped`, `delivered`, `completed`, `cancelled` a `rejected`; nepovinný): Stav objednávky.
* `payment_status` (jedna z hodnot `pending`, `authorized`, `paid`, `failed`, `refunded` a `partially_refunded`; nepovinný): Stav platby.

**Obálka odpovědi**

* `data` (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
* `next_cursor` (text nebo `null`): Kurzor další stránky, `null` = tohle je poslední stránka.
* `next_updated_since` (čas ISO 8601): Hodnota `updated_since` pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

**Pole záznamu**

* `id` (UUID)
* `order_number` (text): Číslo objednávky, jak ho vidí zákazník.
* `status` (jedna z hodnot `pending`, `received`, `confirmed`, `processing`, `shipped`, `delivered`, `completed`, `cancelled` a `rejected`)
* `payment_status` (jedna z hodnot `pending`, `authorized`, `paid`, `failed`, `refunded` a `partially_refunded`)
* `payment_method` (jedna z hodnot `card_online`, `apple_pay`, `google_pay`, `bank_transfer`, `cod` a `invoice`)
* `fulfillment_status` (jedna z hodnot `pending`, `label_created`, `handed_over`, `in_transit`, `ready_for_pickup`, `delivered`, `returned`, `failed` a `cancelled`, nebo `null`): Stav nejnovější zásilky, `null` bez zásilky. Vznik i posun zásilky posune `updated_at` objednávky; podrobnosti zásilky jsou v `/shipments`.
* `currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `subtotal_minor` (celé číslo): Zboží celkem v haléřích, s DPH.
* `discount_total_minor` (celé číslo): Sleva celkem v haléřích.
* `shipping_price_minor` (celé číslo): Doprava v haléřích, s DPH.
* `total_minor` (celé číslo): K úhradě celkem v haléřích, s DPH.
* `email` (text)
* `phone` (text nebo `null`)
* `is_quotation` (`true` nebo `false`): `true` = velkoobchodní poptávka, ne závazná objednávka.
* `placed_at` (čas ISO 8601)
* `created_at` (čas ISO 8601)
* `updated_at` (čas ISO 8601): Poslední změna záznamu objednávky. Podle něj stránkuje `updated_since`.

**Chyby této cesty**

* **400** `invalid_query`: Parametr dotazu má neplatnou hodnotu: čas v updated\_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
* **400** `invalid_cursor`: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated\_since). Začněte průchod znovu bez cursor.
* **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.

## `GET /api/v1/orders/{id}` [#get-api-v1-orders-id]

Jedna objednávka i s položkami, fakturační a doručovací adresou a variabilním symbolem.

* **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“.
* **Odpověď:** jeden záznam v `data`.

```bash
curl -s "https://muj-eshop.cz/api/v1/orders/$ID" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"
```

**Parametry v cestě**

* `id` (UUID; povinný): Identifikátor záznamu (UUID) z výpisu.

**Obálka odpovědi**

* `data` (záznam): Jeho pole popisuje seznam Pole záznamu.

**Pole záznamu**

* `id` (UUID)
* `order_number` (text): Číslo objednávky, jak ho vidí zákazník.
* `status` (jedna z hodnot `pending`, `received`, `confirmed`, `processing`, `shipped`, `delivered`, `completed`, `cancelled` a `rejected`)
* `payment_status` (jedna z hodnot `pending`, `authorized`, `paid`, `failed`, `refunded` a `partially_refunded`)
* `payment_method` (jedna z hodnot `card_online`, `apple_pay`, `google_pay`, `bank_transfer`, `cod` a `invoice`)
* `fulfillment_status` (jedna z hodnot `pending`, `label_created`, `handed_over`, `in_transit`, `ready_for_pickup`, `delivered`, `returned`, `failed` a `cancelled`, nebo `null`): Stav nejnovější zásilky, `null` bez zásilky. Vznik i posun zásilky posune `updated_at` objednávky; podrobnosti zásilky jsou v `/shipments`.
* `currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `subtotal_minor` (celé číslo): Zboží celkem v haléřích, s DPH.
* `discount_total_minor` (celé číslo): Sleva celkem v haléřích.
* `shipping_price_minor` (celé číslo): Doprava v haléřích, s DPH.
* `total_minor` (celé číslo): K úhradě celkem v haléřích, s DPH.
* `email` (text)
* `phone` (text nebo `null`)
* `is_quotation` (`true` nebo `false`): `true` = velkoobchodní poptávka, ne závazná objednávka.
* `placed_at` (čas ISO 8601)
* `created_at` (čas ISO 8601)
* `updated_at` (čas ISO 8601): Poslední změna záznamu objednávky. Podle něj stránkuje `updated_since`.
* `billing` (objekt)
* `billing.name` (text)
* `billing.company` (text nebo `null`)
* `billing.ico` (text nebo `null`)
* `billing.dic` (text nebo `null`)
* `billing.street` (text)
* `billing.city` (text)
* `billing.postal_code` (text)
* `billing.country` (text)
* `shipping` (objekt)
* `shipping.name` (text nebo `null`)
* `shipping.street` (text nebo `null`)
* `shipping.city` (text nebo `null`)
* `shipping.postal_code` (text nebo `null`)
* `shipping.country` (text nebo `null`)
* `shipping.pickup_point_label` (text nebo `null`)
* `shipping.carrier_code` (jedna z hodnot `packeta`, `personal`, `balikovna`, `cp`, `ppl`, `dpd`, `gls` a `printify`, nebo `null`)
* `variable_symbol` (text nebo `null`)
* `notes` (text nebo `null`): Poznámka zákazníka k objednávce.
* `lines` (pole objektů)
* `lines[].id` (UUID)
* `lines[].product_id` (UUID nebo `null`)
* `lines[].variant_id` (UUID nebo `null`)
* `lines[].sku` (text nebo `null`)
* `lines[].name` (text): Název položky v okamžiku objednávky.
* `lines[].quantity` (celé číslo)
* `lines[].unit_price_minor` (celé číslo): Jednotková cena v haléřích, s DPH.
* `lines[].line_discount_minor` (celé číslo)
* `lines[].line_total_minor` (celé číslo)
* `lines[].vat_rate` (celé číslo od 0 do 100): Sazba DPH v celých procentech.

**Chyby této cesty**

* **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.
* **404** `not_found`: Záznam s tímhle identifikátorem v obchodě není.

## `GET /api/v1/returns` [#get-api-v1-returns]

Vratky a reklamace i s položkami, důvodem a stavem vrácení peněz v haléřích, s odkazem na objednávku a na vystavený dobropis.

* **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“.
* **Odpověď:** stránka výpisu, záznamy jsou v `data` a jak otevřít další stránku, říká seznam Obálka odpovědi.
* **Synchronizace:** s `updated_since` se výpis řadí podle pole `updated_at` od nejstarší změny, bez něj od nejnovějšího záznamu.

```bash
curl -s "https://muj-eshop.cz/api/v1/returns?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"
```

**Parametry dotazu**

* `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
* `cursor` (text; nepovinný): Hodnota `next_cursor` z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
* `updated_since` (čas ISO 8601; nepovinný): ISO 8601 se zónou `Z` nebo s číselným posunem (`+02:00`). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota `next_updated_since` jde do adresy vložit bez kódování; `+` z nezakódované adresy se čte jako `+`.
* `status` (jedna z hodnot `requested`, `received`, `approved`, `partially_approved`, `rejected`, `refunded`, `closed` a `cancelled`; nepovinný): Stav vratky.

**Obálka odpovědi**

* `data` (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
* `next_cursor` (text nebo `null`): Kurzor další stránky, `null` = tohle je poslední stránka.
* `next_updated_since` (čas ISO 8601): Hodnota `updated_since` pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

**Pole záznamu**

* `id` (UUID)
* `return_number` (text)
* `order_id` (UUID)
* `order_number` (text)
* `regime` (jedna z hodnot `withdrawal`, `reklamace` a `seller_cancel`): withdrawal = odstoupení od smlouvy, reklamace = vada zboží, seller\_cancel = zrušeno prodejcem (dodavatel zboží nemůže dodat, nejde o odstoupení zákazníka).
* `status` (jedna z hodnot `requested`, `received`, `approved`, `partially_approved`, `rejected`, `refunded`, `closed` a `cancelled`)
* `reason` (jedna z hodnot `changed_mind`, `better_price`, `wrong_size`, `looks_different`, `arrived_late`, `no_longer_needed`, `defective`, `damaged_in_transit`, `wrong_item`, `missing_parts`, `not_as_described`, `quality_issue` a `other`, nebo `null`)
* `refund` (objekt)
* `refund.currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `refund.requested_minor` (celé číslo): Kolik zákazník požadoval.
* `refund.approved_minor` (celé číslo): Kolik obchod schválil, i s poštovným.
* `refund.shipping_minor` (celé číslo): Vrácené poštovné (§ 1832 OZ).
* `refund.refunded_minor` (celé číslo): Kolik se už opravdu vrátilo.
* `credit_note_id` (UUID nebo `null`): Vystavený dobropis k vratce, identifikátor pro `/documents/{id}`.
* `credit_note_number` (text nebo `null`)
* `deadline_at` (čas ISO 8601 nebo `null`): Lhůta vyřízení reklamace (zákonná, nebo dohodnutá delší).
* `items` (pole objektů)
* `items[].id` (UUID)
* `items[].order_line_id` (UUID)
* `items[].variant_id` (UUID nebo `null`)
* `items[].sku` (text nebo `null`)
* `items[].name` (text)
* `items[].quantity_requested` (celé číslo)
* `items[].quantity_approved` (celé číslo)
* `items[].unit_price_gross_minor` (celé číslo)
* `items[].currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `items[].vat_rate` (celé číslo od 0 do 100)
* `items[].reason` (jedna z hodnot `changed_mind`, `better_price`, `wrong_size`, `looks_different`, `arrived_late`, `no_longer_needed`, `defective`, `damaged_in_transit`, `wrong_item`, `missing_parts`, `not_as_described`, `quality_issue` a `other`, nebo `null`)
* `created_at` (čas ISO 8601)
* `updated_at` (čas ISO 8601)

**Chyby této cesty**

* **400** `invalid_query`: Parametr dotazu má neplatnou hodnotu: čas v updated\_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
* **400** `invalid_cursor`: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated\_since). Začněte průchod znovu bez cursor.
* **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.

## `GET /api/v1/returns/{id}` [#get-api-v1-returns-id]

Jedna vratka nebo reklamace, v témže tvaru jako ve výpisu.

* **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“.
* **Odpověď:** jeden záznam v `data`.

```bash
curl -s "https://muj-eshop.cz/api/v1/returns/$ID" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"
```

**Parametry v cestě**

* `id` (UUID; povinný): Identifikátor záznamu (UUID) z výpisu.

**Obálka odpovědi**

* `data` (záznam): Jeho pole popisuje seznam Pole záznamu.

**Pole záznamu**

* `id` (UUID)
* `return_number` (text)
* `order_id` (UUID)
* `order_number` (text)
* `regime` (jedna z hodnot `withdrawal`, `reklamace` a `seller_cancel`): withdrawal = odstoupení od smlouvy, reklamace = vada zboží, seller\_cancel = zrušeno prodejcem (dodavatel zboží nemůže dodat, nejde o odstoupení zákazníka).
* `status` (jedna z hodnot `requested`, `received`, `approved`, `partially_approved`, `rejected`, `refunded`, `closed` a `cancelled`)
* `reason` (jedna z hodnot `changed_mind`, `better_price`, `wrong_size`, `looks_different`, `arrived_late`, `no_longer_needed`, `defective`, `damaged_in_transit`, `wrong_item`, `missing_parts`, `not_as_described`, `quality_issue` a `other`, nebo `null`)
* `refund` (objekt)
* `refund.currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `refund.requested_minor` (celé číslo): Kolik zákazník požadoval.
* `refund.approved_minor` (celé číslo): Kolik obchod schválil, i s poštovným.
* `refund.shipping_minor` (celé číslo): Vrácené poštovné (§ 1832 OZ).
* `refund.refunded_minor` (celé číslo): Kolik se už opravdu vrátilo.
* `credit_note_id` (UUID nebo `null`): Vystavený dobropis k vratce, identifikátor pro `/documents/{id}`.
* `credit_note_number` (text nebo `null`)
* `deadline_at` (čas ISO 8601 nebo `null`): Lhůta vyřízení reklamace (zákonná, nebo dohodnutá delší).
* `items` (pole objektů)
* `items[].id` (UUID)
* `items[].order_line_id` (UUID)
* `items[].variant_id` (UUID nebo `null`)
* `items[].sku` (text nebo `null`)
* `items[].name` (text)
* `items[].quantity_requested` (celé číslo)
* `items[].quantity_approved` (celé číslo)
* `items[].unit_price_gross_minor` (celé číslo)
* `items[].currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `items[].vat_rate` (celé číslo od 0 do 100)
* `items[].reason` (jedna z hodnot `changed_mind`, `better_price`, `wrong_size`, `looks_different`, `arrived_late`, `no_longer_needed`, `defective`, `damaged_in_transit`, `wrong_item`, `missing_parts`, `not_as_described`, `quality_issue` a `other`, nebo `null`)
* `created_at` (čas ISO 8601)
* `updated_at` (čas ISO 8601)

**Chyby této cesty**

* **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.
* **404** `not_found`: Záznam s tímhle identifikátorem v obchodě není.

## `GET /api/v1/shipments` [#get-api-v1-shipments]

Zásilky objednávek: dopravce, způsob dopravy, číslo a odkaz pro sledování, stav a položky v zásilce. Štítek ani chybová hlášení dopravce ven nejdou.

* **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“.
* **Odpověď:** stránka výpisu, záznamy jsou v `data` a jak otevřít další stránku, říká seznam Obálka odpovědi.
* **Synchronizace:** s `updated_since` se výpis řadí podle pole `updated_at` od nejstarší změny, bez něj od nejnovějšího záznamu.

```bash
curl -s "https://muj-eshop.cz/api/v1/shipments?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"
```

**Parametry dotazu**

* `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
* `cursor` (text; nepovinný): Hodnota `next_cursor` z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
* `updated_since` (čas ISO 8601; nepovinný): ISO 8601 se zónou `Z` nebo s číselným posunem (`+02:00`). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota `next_updated_since` jde do adresy vložit bez kódování; `+` z nezakódované adresy se čte jako `+`.
* `status` (jedna z hodnot `pending`, `label_created`, `handed_over`, `in_transit`, `ready_for_pickup`, `delivered`, `returned`, `failed` a `cancelled`; nepovinný): Stav zásilky.

**Obálka odpovědi**

* `data` (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
* `next_cursor` (text nebo `null`): Kurzor další stránky, `null` = tohle je poslední stránka.
* `next_updated_since` (čas ISO 8601): Hodnota `updated_since` pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

**Pole záznamu**

* `id` (UUID)
* `order_id` (UUID)
* `order_number` (text)
* `carrier` (jedna z hodnot `packeta`, `personal`, `balikovna`, `cp`, `ppl`, `dpd`, `gls` a `printify`)
* `service` (text nebo `null`): Způsob dopravy, jak ho zákazník vybral v pokladně.
* `delivery_type` (jedna z hodnot `shipping`, `pickup_point` a `personal_pickup`, nebo `null`)
* `status` (jedna z hodnot `pending`, `label_created`, `handed_over`, `in_transit`, `ready_for_pickup`, `delivered`, `returned`, `failed` a `cancelled`)
* `tracking_number` (text nebo `null`)
* `tracking_url` (text nebo `null`)
* `pickup_point_id` (text nebo `null`)
* `parcel_count` (celé číslo)
* `weight_grams` (celé číslo nebo `null`)
* `currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `cod_amount_minor` (celé číslo nebo `null`): Dobírka v haléřích, `null` bez dobírky.
* `handed_over_at` (čas ISO 8601 nebo `null`)
* `delivered_at` (čas ISO 8601 nebo `null`)
* `items` (pole objektů): Položky přiřazené k zásilce. Prázdné pole = zásilka není rozepsaná po položkách.
* `items[].order_line_id` (UUID)
* `items[].sku` (text nebo `null`)
* `items[].name` (text)
* `items[].quantity` (celé číslo)
* `created_at` (čas ISO 8601)
* `updated_at` (čas ISO 8601)

**Chyby této cesty**

* **400** `invalid_query`: Parametr dotazu má neplatnou hodnotu: čas v updated\_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
* **400** `invalid_cursor`: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated\_since). Začněte průchod znovu bez cursor.
* **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.