# Create a Shipment

Endpoint: POST /shipments
Version: V5
Security: basicAuth

## Request fields (application/json):

  - `merchant_invoice_id` (string, required)
    ID of the merchant invoice this shipment belongs to.
    Example: "inv_1234567890abcdef"

  - `fulfillment_method` (string)
    Method of fulfillment for the shipment. Determines what additional fields are required:
- shipping_provider: Requires shipment_tracking_number and shipment_courier. File is not allowed.
- self_delivery, customer_pickup, services_only: Require a file. Tracking number and courier are optional.
    Enum: "shipping_provider", "self_delivery", "customer_pickup", "services_only"

  - `shipment_tracking_number` (string)
    Tracking number (required when fulfillment_method is shipping_provider, optional otherwise).
    Example: "1Z123E45678901234"

  - `shipment_courier` (string)
    Shipping courier (required when fulfillment_method is shipping_provider, optional otherwise). While any value can be accepted, instant verification is supported for specific couriers.

See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.
    Example: "ups"

  - `file` (object)

  - `file.url` (string, required)
    S3 URL of the uploaded file obtained after uploading to the signed URL from /shipments/sign-upload.
    Example: "https://bucket.s3.amazonaws.com/1234567890-document.pdf"

  - `file.size` (integer, required)
    File size in bytes.
    Example: 204800

  - `file.metadata` (object)
    Optional metadata about the file.
    Example: {"original_filename":"proof_of_delivery.pdf"}

  - `file.metadata.original_filename` (string)
    Original filename before upload.
    Example: "proof_of_delivery.pdf"

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier of the Shipment.
    Example: "ship_1234567890abcdef"

  - `merchant_invoice_id` (string)
    ID of the associated merchant invoice.
    Example: "inv_1234567890abcdef"

  - `fulfillment_method` (string)
    Method of fulfillment for the shipment.
    Enum: "shipping_provider", "self_delivery", "customer_pickup", "services_only"

  - `shipment_tracking_number` (string)
    Tracking number provided by the shipping courier.
    Example: "1Z123E45678901234"

  - `shipment_courier` (string)
    Shipping courier or provider name. While any value can be accepted, instant verification is supported for specific couriers.

See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.
    Example: "ups"

  - `verification_status` (string)
    Manual or automatic verification status of the shipment.
    Enum: "verified", "pending"

  - `created_at` (string)
    Date time when the shipment was created.
    Example: "2024-01-15T10:30:00Z"

  - `updated_at` (string)
    Date time when the shipment was last updated.
    Example: "2024-01-15T14:45:00Z"

  - `tracking_status` (string,null)
    Current tracking status of the shipment from the courier.
    Example: "delivered"

  - `tracking_substatus` (string,null)
    Detailed tracking substatus providing additional context about the shipment's current state.
    Example: "delivered_001"

  - `expected_delivery` (string,null)
    Expected delivery date and time provided by the shipping courier.
    Example: "2024-01-20T18:00:00Z"

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: "Invalid merchant credentials"

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 404 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: "[entity] not found"

  - `error.type` (string)
    A short string, describing error type
    Enum: "not_found_error"

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: "Too many requests"

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"