---
title: "Create a new shipment with tracking information"
method: POST
path: "/api/v1/workflow/agent/brand-actions/create-shipment"
tags: ["Workflow - Brand Actions"]
---

# Create a new shipment with tracking information

`POST /api/v1/workflow/agent/brand-actions/create-shipment`

## Request

- Base URL: `https://api.kolect.com`
- URL: `https://api.kolect.com/api/v1/workflow/agent/brand-actions/create-shipment`
- Auth: HTTP bearer

Creates a new shipment for a partnership by validating the tracking number,
saving tracking information to the database, and notifying the creator via webhook.
This endpoint replaces the legacy update-shipment workflow by using the new
partnership_tracking table and automatic tracking validation.

## Request body

- object
  - `partnership_id` string, uuid, required: The ID of the campaign partnership
  - `tracking_number` string, required: Package tracking number from shipping carrier
  - `carrier_name` string: Optional carrier name to force use of specific tracking API (e.g., "cainiao")

## Response `200`

Shipment created successfully

- object
  - `success` boolean
  - `data` object
    - `partnership_id` string, uuid: The partnership ID
    - `tracking_number` string: The validated tracking number
    - `carrier_name` string: Shipping carrier name (auto-detected)
    - `tracking_status` 'shipped' | 'delivered' | 'failed': Normalized tracking status from API
    - `shipment_status` 'in transit' | 'delivered': Shipment status sent to webhook
    - `partnership_tracking_updated` boolean: Whether partnership tracking was saved to database
    - `tracking_id` string, uuid: ID of the tracking record in partnership_tracking table

## Other responses

- `400`: Bad request - validation failed
- `404`: Partnership not found
- `500`: Server error

---

[API](https://skmtc.dev/kolect/apis/kolect-api.md) · [All operations](https://skmtc.dev/kolect/apis/kolect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolect/apis/kolect-api/revisions/fe54528e8f54?raw)