Delivery Statuses
Release delivery is not one synchronous API call. A release moves through draft preparation, readiness checks, review, downstream delivery, and destination-specific outcomes.
Status fields
| Field | Meaning |
|---|---|
status | General release state shown on release records and queues. |
review_id | Public review reference when the release is in a review workflow. |
review_status | Organization-visible review state. |
delivery_status | Organization-visible delivery state after review or delivery processing begins. |
delivery_simulated | true when staging completed the lifecycle locally without external delivery. |
submitted_at | Timestamp for when submission was recorded, when available. |
Integration sequence
- Keep the release as a draft while metadata, artwork, audio, rights, and destinations are incomplete.
- Run
GET /api/v1/releases/{release_id}/pre-qcbefore submission. - Submit with
POST /api/v1/releases/{release_id}/submitonly when no blocking issue remains. - Monitor submitted releases through release review endpoints available to the authenticated organization.
- Monitor sent or delivered release queues for delivery outcomes.
Draft and readiness states
| State | Meaning | Client action |
|---|---|---|
| Draft | Release is editable and not submitted. | Continue adding metadata, tracks, rights, and distribution. |
| Readiness has blocking issues | Pre-submission checks found missing or invalid data. | Fix the fields listed by the readiness response. Do not submit. |
| Readiness has warnings | The release may be close to valid but needs operator review. | Decide whether to fix warnings before submission. |
| Ready to submit | No blocking issue remains. | Submit once the operator confirms metadata and destinations. |
Review states
Actual values are returned by the API and can evolve, but integrations should handle these state families:
| State family | Meaning | Client action |
|---|---|---|
submitted or pending_review | Release is waiting for review. | Poll at a moderate interval. Do not resubmit in a tight loop. |
in_review | Review is active. | Avoid metadata changes unless the endpoint allows them. |
changes_requested or rejected | Review found blocking issues. | Read the reason, fix metadata or assets, then resubmit when allowed. |
approved | Review accepted the release for delivery. | Monitor delivery status. |
sent | Release was sent onward for delivery. | Monitor destination outcome. |
Clients must be tolerant of additional status values and display unknown values without crashing.
Delivery states
| State family | Meaning | Client action |
|---|---|---|
pending_review | Delivery has not started because review is still pending. | Wait for review outcome. |
queued or processing | Delivery is being prepared or sent. | Poll with a longer interval. |
sent | Delivery package was sent onward. | Wait for downstream result. |
delivered | Release is marked delivered in the visible workflow. | Store the status and stop frequent polling. |
failed or rejected | Delivery failed or was rejected. | Read the reason and fix the root cause before resubmission. |
partial | Some destinations accepted or progressed while others did not. | Show destination-level detail when available and resolve failed destinations. |
Do not treat sent as the same as live on every DSP. Storefront availability can lag behind delivery acceptance.
On staging, no status represents real DSP delivery. A terminal simulated result includes delivery_simulated: true; use it to validate client behavior, retries, polling, and operator displays.
Polling intervals
| Workflow | Endpoint | Fields to inspect | Suggested interval | Stop condition |
|---|---|---|---|---|
| Readiness | GET /api/v1/releases/{release_id}/pre-qc | Blocking and warning issue groups returned by the check. | Run after each metadata or asset fix. | No blocking issue remains, or the operator leaves the edit flow. |
| Submitted review queue | GET /api/v1/qc/releases/submitted | review_id, review_status, delivery_status, submitted_at, release fields. | 30 to 60 seconds while an operator is waiting. | Release leaves submitted review, needs changes, or is no longer relevant to the operator. |
| Sent review queue | GET /api/v1/qc/releases/sent | review_id, delivery_status, submitted_at, release fields. | 5 to 30 minutes. | Delivery reaches a terminal state or moves into manual handling. |
| All visible review queue | GET /api/v1/qc/releases/all | Same queue fields plus list pagination metadata. | 5 to 15 minutes for background sync. | Local state is synchronized through the latest page. |
| Checkout result | Matching checkout verify or status endpoint. | checkout_id, payment status fields, related billing or add-on state. | After provider return, then back off. | Checkout is complete, failed, cancelled, or expired. |
Common blockers
| Blocker | Cause | Fix |
|---|---|---|
| Release stays in draft | Submission was never called or readiness checks failed. | Run readiness checks and submit only after blockers are fixed. |
| Submission fails | Missing metadata, missing rights, invalid cover art, no tracks, or no destinations. | Fix the validation errors and rerun readiness checks. |
| Review rejects release | Metadata, rights, artwork, or audio does not meet delivery requirements. | Fix the listed issue, then resubmit if allowed. |
| Delivery is partial | One or more destinations need different metadata, territory, or rights handling. | Inspect destination-level details when returned and resolve only the failed destinations. |
| Status is unknown to the client | API added or returned a status the client did not map. | Display the raw value and log it for mapping update. |
Common questions
Does sent mean the release is live?
No. It means the delivery package went onward. Storefront availability lags behind delivery acceptance and varies per destination.
What should my client do with a status it has never seen? Display the raw value, log the endpoint and public reference, and keep the record visible to an operator. Never let an unknown status trigger irreversible automation.
How often should I poll? As slowly as the workflow tolerates. 30 to 60 seconds while an operator is watching a submitted release, 5 to 30 minutes for delivery outcomes, and longer for background sync.
A staging release shows delivered. Does that prove anything?
Only that your client handled the contract correctly. Check delivery_simulated. On staging it is true and no release ever reaches a store.
Next
Was this page helpful?