Skip to content
ShirteeShirtee Developers
DEEN

Polling instead of webhooks

The API sends no webhooks. You learn about changes by polling.

Orders

Section titled “Orders”

The list GET /api/orders is sorted by creation time descending (newest first) and filterable. The status filter is multi-valued: repeat the parameter, for example status=CHECK&status=ERROR. All filters apply together.

For a single order use GET /api/orders/{order_id} with tracking=true. It contains status, retention reason and shipments.

Recommendation:

  • Poll lists at a fixed interval, for example every few minutes, rather than each order individually.
  • Poll single orders only while waiting for a change, and slow down as you go: first seconds apart, then minutes.
  • Stop polling once the order reaches a final status.
  • Watch the budget: RateLimit-Remaining shows how much is left.

Invoice PDF

Section titled “Invoice PDF”

Invoice PDFs are generated in the background on first request. GET /api/invoices/user/{invoice_id}/pdf therefore reports an intermediate state:

Case HTTP status pdf_url
PDF is available 200 ready signed URL
PDF is being generated 202 generating null
PDF will not arrive 200 failed null

While 202 with generating is returned, repeat the same call. A gap of a few seconds is enough. Important:

  • failed is returned with 200, not 202 and not as an error. Check status, not just the HTTP code.
  • The first request triggers generation. Further requests within 5 minutes do not trigger it again. After that it is triggered up to three times in total. failed arrives at the earliest about 15 minutes after the first request.
  • The URL in pdf_url is signed and valid for 15 minutes. Download the PDF immediately or fetch a fresh URL with a new call.
Terminal window
curl -i https://gateway.shirtee.cloud/api/invoices/user/123/pdf \
  -H "Authorization: Bearer $SHIRTEE_API_KEY"

The exact paths and responses are in the API reference.