Brand key required

Shipments

Record product shipments to creators with carrier and tracking number. Roster tracks delivery status and lets the creator confirm receipt.

List shipments

GET/v1/shipments

Parameter	Type	Description
campaign_id	string	Filter to one campaign.
status	string	Filter: created, shipped, in_transit, delivered, returned.
page / limit	integer	Standard pagination.

request

curl "https://api.ugcroster.com/v1/shipments?status=shipped" \
  -H "Authorization: Bearer rsk_brand_key"

response 200

{
  "data": [
    {
      "id": "ship_001",
      "campaign_id": "form_xyz789",
      "creator_email": "emma@example.com",
      "creator_name": "Emma Chen",
      "carrier": "ups",
      "tracking_number": "1Z999AA10123456784",
      "estimated_arrival": null,
      "product_description": "Glow Serum, Moisturizer SPF 30",
      "shipping_address": {
        "street": "1234 Sunset Blvd",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90026",
        "country": "US"
      },
      "notes": null,
      "tracking_status": "pending",
      "tracking_last_update": null,
      "creator_confirmed_receipt": false,
      "creator_confirmed_at": null,
      "status": "shipped",
      "created_at": "2026-06-05T10:00:00Z",
      "updated_at": "2026-06-08T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 18, "has_more": false }
}

GET /v1/shipments/{id} returns the same shape plus tracking_details when carrier tracking data is available.

Create a shipment

POST/v1/shipments

Field	Type	Description
creator_email	string	Required.
tracking_number	string	Required.
carrier	string	Required. Stored lowercased ("UPS" → "ups").
product_description	string	Required. What is in the box.
shipping_address	object \| string	Object with street, line2, city, state, zip, country, or a free-form string. Also accepted as "address".
campaign_id / creator_name	string	Optional linkage and label.
estimated_arrival	string	Optional ISO date.
notes	string	Optional delivery notes.

request

curl -X POST "https://api.ugcroster.com/v1/shipments" \
  -H "Authorization: Bearer rsk_brand_key" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_email": "emma@example.com",
    "campaign_id": "form_new456",
    "product_description": "Fall Collection Box",
    "tracking_number": "1Z999AA10987654321",
    "carrier": "UPS",
    "shipping_address": {
      "street": "1234 Sunset Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90026",
      "country": "US"
    },
    "notes": "Leave at front desk"
  }'

response 200

{
  "data": {
    "id": "ship_new001",
    "creator_email": "emma@example.com",
    "carrier": "ups",
    "tracking_number": "1Z999AA10987654321",
    "product_description": "Fall Collection Box",
    "shipping_address": {
      "street": "1234 Sunset Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90026",
      "country": "US"
    },
    "tracking_status": "pending",
    "creator_confirmed_receipt": false,
    "status": "created",
    "created_at": "2026-06-13T16:40:00Z"
  }
}

Update a shipment

PATCH/v1/shipments/{id}

Field	Type	Description
status	string	created, shipped, in_transit, delivered, returned. Other values are ignored.
tracking_number / carrier	string	Replace tracking details (carrier lowercased).
estimated_arrival	string	ISO date; empty string clears it.
shipping_address	object \| string \| null	Object or free-form string replaces the address; explicit null clears it entirely.
notes	string	Empty string clears the notes.

request: new address as a string

curl -X PATCH "https://api.ugcroster.com/v1/shipments/ship_001" \
  -H "Authorization: Bearer rsk_brand_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "shipping_address": "2715 Bearcat Way, Cincinnati, OH 45219-3539, US",
    "notes": "Address updated by brand"
  }'

response 200

{
  "data": {
    "id": "ship_001",
    "status": "shipped",
    "shipping_address": "2715 Bearcat Way, Cincinnati, OH 45219-3539, US",
    "notes": "Address updated by brand",
    "updated_at": "2026-08-17T16:20:00Z"
  }
}

Address semantics in one line: object or string sets it, omitting leaves it, null clears it. A PATCH body with no recognized fields returns 422 VALIDATION_ERROR.

Campaigns →

Link shipments to a campaign via campaign_id.

Roster →

The creators you are seeding product to.