States
How state active and inactive become listing statuses, moderation, quotas, the item results of a push, what unchanged means, and the 60-day renewal.
Your state, our status#
Every payload says state: "active" (publish) or "inactive" (keep, but not live). The worker applies the agency editor's own publish rules:
| You push | The listing is | Result |
|---|---|---|
active, never published |
new or a draft | first publish: the publish rules run (missing fields → missing_required, no mandate → mandate_missing); verified agency → live at once, unverified agency → published but waiting for moderation |
active |
paused, sold, rented, expired or archived | revived: published again; moderation is not re-run |
active |
published | updated; a material change (e.g. the price) can send it back to moderation, as in the editor |
inactive |
published | paused |
inactive |
not published | stays a draft |
Every active push renews the listing's expiry by 60 days.
Moderation#
- An unverified agency's listings are published with moderation pending: they are invisible until Novi Kvadrat staff approve them.
- A listing staff rejected or removed in moderation is never re-published by a push: the item fails with
moderation_blocked. The agency sees the moderation note in its portal. You getlisting.moderation_changedwhen staff change a managed listing's moderation.
Quota#
The agency's plan limits its live listings. The quota is checked on every move into a live status — a first publish, a revive, and an inactive → active flip. At the cap the item fails with quota_exceeded; the next push retries. (Pushing a thousand inactive drafts and flipping them active is charged at the flip.)
Item results#
Every push answers one result per listing at once:
| Result | Meaning | What follows |
|---|---|---|
accepted |
valid and staged | item.imported (live) or item.validated (sandbox), or item.failed |
unchanged |
same content as the last import, or source.updated_at older than the one we hold; nothing queued |
the listing's 60-day expiry is renewed; no webhook |
needs_review |
the connection is certifying, or the duplicate rule held it | resolved by staff; then imported, or item.failed (duplicate, certification_rejected) |
rejected |
failed validation (batch only; a single PUT answers 422); nothing is staged |
fix and push again |
removed |
the removal is recorded | applied at once (never went live) or on the next tick; item.removed |
Failures after staging arrive as item.failed with one of: missing_required, quota_exceeded, duplicate, photo_fetch_failed, photo_minimum, mandate_missing, moderation_blocked, worker_error; staff write certification_rejected.
What "unchanged" means#
We compute a digest over the validated payload in canonical JSON (sorted keys, no whitespace), so key order and formatting don't matter, but any value change does — including photo order and captions. Your own digest field is echoed, never compared. An unchanged push still renews the expiry, so pushing your full stock hourly is safe and cheap. A removed listing never answers unchanged: pushing it again revives it (unless moderation blocks it).
Duplicates#
When a new listing looks like one the agency already published by hand (same place, same normalised address, area within 2 m²), the item answers needs_review with duplicate and the webhook item.review_required fires. Staff link it to the existing listing, create a new one, or dismiss it (item.failed with duplicate).
Expiry#
A listing you stop pushing expires 60 days after the last push that renewed it: the status becomes expired and the webhook listing.expired fires. Push it again with state: "active" to revive it.
Last updated