🚚 Deliveries

Album delivery records to digital platforms (DSPs)

Resource Overview

Deliveries represent successful or failed album deliveries to specific platforms (DSPs). They are the final result of the distribution process and provide complete traceability of each delivery status. This is a read-only resource - deliveries are created and updated automatically by the system.

Base Endpoint
/deliveries
Resource Type
deliveries
Access Type
Read-Only
User Scope
Owner-restricted

Schema

Read-Only Resource

All fields are read-only. Deliveries are generated automatically by the system during the distribution process.

System-Generated Attributes

Field Type Description Read-Only
id integer Unique delivery identifier ✓
date datetime Delivery date and time ✓
type string Delivery type (delivery, update, redelivery, takedown) ✓
status string Delivery status (pending, sent, error) ✓
errors string Error details if delivery failed ✓
created-at datetime Record creation date ✓
updated-at datetime Last update date ✓

Relationships

Relationship Type Description Required
dsp BelongsTo Target digital platform Required
album BelongsTo Album that was delivered Required

API Endpoints

GET /deliveries

Get list of deliveries for the authenticated user

Query Parameters

  • • filter[album]=1 - Filter by specific album
  • • filter[dsp]=2 - Filter by specific DSP
  • • filter[status]=sent - Filter by status
  • • filter[type]=delivery - Filter by type
  • • include=album,dsp - Include relationships
  • • page[number]=1&page[size]=20 - Pagination
  • • sort=-date - Sort by date (most recent first)
  • • filter[album]=1 - Filtrar por álbum específico
  • • filter[dsp]=2 - Filtrar por DSP específico
  • • filter[status]=success - Filtrar por estado
  • • filter[type]=delivery - Filtrar por tipo
  • • include=album,dsp - Incluir relaciones
  • • page[number]=1&page[size]=20 - Paginación
  • • sort=-date - Ordenar por fecha (más recientes primero)

Success Response

200 OK 
{
  "data": [
    {
      "type": "deliveries",
      "id": "1",
      "attributes": {
        "date": "2024-08-21",
        "type": "delivery",
        "status": "sent",
        "errors": null,
        "created-at": "2024-08-21T08:30:00Z",
        "updated-at": "2024-08-21T08:45:00Z"
      },
      "relationships": {
        "dsp": {
          "data": {
            "type": "dsps",
            "id": "1"
          }
        },
        "album": {
          "data": {
            "type": "albums",
            "id": "1"
          }
        }
      }
    },
    {
      "type": "deliveries",
      "id": "2",
      "attributes": {
        "date": "2024-08-21",
        "type": "delivery",
        "status": "error",
        "errors": "Invalid metadata: Missing required field 'ISRC'",
        "created-at": "2024-08-21T09:15:00Z",
        "updated-at": "2024-08-21T09:30:00Z"
      },
      "relationships": {
        "dsp": {
          "data": {
            "type": "dsps",
            "id": "2"
          }
        },
        "album": {
          "data": {
            "type": "albums",
            "id": "1"
          }
        }
      }
    }
  ],
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 1,
      "perPage": 20,
      "to": 2,
      "total": 2
    }
  }
}
GET /deliveries/{id}

Get a specific delivery

Success Response

200 OK 
{
  "data": {
    "type": "deliveries",
    "id": "1",
    "attributes": {
      "date": "2024-08-21",
      "type": "delivery",
      "status": "sent",
      "errors": null,
      "created-at": "2024-08-21T08:30:00Z",
      "updated-at": "2024-08-21T08:45:00Z"
    },
    "relationships": {
      "dsp": {
        "data": {
          "type": "dsps",
          "id": "1"
        }
      },
      "album": {
        "data": {
          "type": "albums",
          "id": "1"
        }
      }
    }
  },
  "included": [
    {
      "type": "dsps",
      "id": "1",
      "attributes": {
        "name": "Spotify",
        "website": "https://spotify.com"
      }
    },
    {
      "type": "albums",
      "id": "1",
      "attributes": {
        "title": "Midnight Dreams",
        "artwork": "https://example.com/artwork.jpg"
      }
    }
  ]
}

Delivery Status Flow

⏳

Pending

Delivery in process of being sent to DSP

✅

Sent

Album successfully sent to DSP

❌

Error

Delivery error, check errors field

Delivery Types

delivery

First album delivery to DSP

update

Metadata or tracks update

redelivery

Update delivery with modified assets

takedown

Album removal from DSP

Use Cases

📊 Delivery Monitoring

Monitor delivery status for a specific album

# Get all deliveries for an album
GET /deliveries?filter[album]=1&include=dsp

# Check failed deliveries
GET /deliveries?filter[status]=error&include=album,dsp

# Monitor recent deliveries
GET /deliveries?sort=-date&page[size]=10

🔍 DSP Performance Analysis

Analyze delivery performance by DSP

# Get Spotify deliveries
GET /deliveries?filter[dsp]=1&include=album

# Compare success rates by DSP
GET /deliveries?filter[status]=sent&include=dsp

# Check error patterns
GET /deliveries?filter[status]=error&include=dsp

🚨 Error Tracking

Track and diagnose delivery errors

# Get deliveries with errors
GET /deliveries?filter[status]=error

# Check specific delivery details
GET /deliveries/123?include=album,dsp

# Monitor error trends by date
GET /deliveries?filter[status]=error&sort=-date

Important Notes

Completely Read-Only

There are no POST, PATCH or DELETE endpoints. Deliveries are created and updated automatically by the system during the distribution process.

User Scope

You can only see deliveries from your own albums. User filtering is applied automatically.

Real-time Tracking

Deliveries are updated in real-time as DSPs process the deliveries.

Error Details

The "errors" field contains detailed information when a delivery fails, useful for debugging.