Order Lifecycle

Partner integrations usually poll orders, advance status when packing/shipping, and attach an invoice URL after shipment.

Status codes

Code	Admin label	API `status`
`1`	Ödeme Bekliyor	`AwaitingPayment`
`2`	Hazırlanıyor	`Picking`
`3`	Kargoda	`Shipped`
`4`	Teslim Edildi	`Delivered`
`5`	İptal Edildi	`Cancelled`

Typical flow

AwaitingPayment (1) — waiting for payment confirmation
Picking (2) — preparing / packing
Shipped (3) — handed to carrier
Delivered (4) — customer received

Cancelled (5) can occur from several stages when the order is cancelled.

Cargo fields: Set cargoCompany and trackingNumber (or snake_case aliases) usually together with status 3 (Shipped). You can update cargo without changing status if at least one of status / cargo / tracking is sent.

Polling strategy

List with page=0 (0-based) and a sensible size (max 100)
Filter with status (e.g. 2 for picking) or 0 for all
Date window: date_from / date_to (YYYY-MM-DD or datetime)
Or Trendyol-compatible Unix ms: startDate / endDate

Permissions: Listing and reading need orders.read. Status / cargo updates and invoice attach need orders.write. Web API v1 has no order webhooks — poll on a schedule.

Invoice

After shipment, attach a public PDF/image URL via POST /orders/{id}/invoice. File upload through the Web API is not supported.

cURL

# 1) List picking orders (status=2), page is 0-based
curl -s -H "X-API-Key: YOUR_API_KEY" -H "Accept: application/json" \
  "https://example.com/api/v1/orders?page=0&size=20&status=2&date_from=2026-06-01&date_to=2026-07-30"

# 2) Mark order 15 as shipped + cargo tracking
curl -s -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": 3,
    "cargoCompany": "Yurtiçi Kargo",
    "trackingNumber": "YT123456789"
  }' \
  "https://example.com/api/v1/orders/15"

# 3) Attach public invoice URL
curl -s -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "url": "https://example.com/fatura.pdf",
    "name": "Fatura"
  }' \
  "https://example.com/api/v1/orders/15/invoice"