---
title: "Create a Shipment"
method: POST
path: "/shipments"
tags: ["Shipments"]
---

# Create a Shipment

`POST /shipments`

## Request

- Base URL: `https://app-sandbox.resolvepay.com/api`
- URL: `https://app-sandbox.resolvepay.com/api/shipments`
- Auth: one of:
  - HTTP bearer
  - HTTP basic
- TypeScript: <https://skmtc.dev/resolvepay/apis/resolve-api-reference/docs/shipments/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- union
  - object
    - `merchant_invoice_id` string, required: ID of the merchant invoice this shipment belongs to.
    - `fulfillment_method` 'shipping_provider' | 'self_delivery' | 'customer_pickup' | 'services_only': 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 legacy `file` or an accepted `file_id`. Tracking number and courier are optional.
    - `shipment_tracking_number` string: Tracking number (required when fulfillment_method is shipping_provider, optional otherwise).
    - `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.
    - `send_email` boolean: Whether to send the buyer an invoice updated email.
    - `file` ShipmentFile, required
      - `url` string, uri, required: S3 URL of the uploaded file obtained after uploading to the signed URL from `/shipments/sign-upload`.
      - `size` integer, required: File size in bytes.
      - `metadata` object: Optional metadata about the file.
        - `original_filename` string: Original filename before upload.
    - `file_id` string: Accepted file_id returned by /shipments/documents. Use instead of file.
  - object
    - `merchant_invoice_id` string, required: ID of the merchant invoice this shipment belongs to.
    - `fulfillment_method` 'shipping_provider' | 'self_delivery' | 'customer_pickup' | 'services_only': 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 legacy `file` or an accepted `file_id`. Tracking number and courier are optional.
    - `shipment_tracking_number` string: Tracking number (required when fulfillment_method is shipping_provider, optional otherwise).
    - `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.
    - `send_email` boolean: Whether to send the buyer an invoice updated email.
    - `file` ShipmentFile
      - `url` string, uri, required: S3 URL of the uploaded file obtained after uploading to the signed URL from `/shipments/sign-upload`.
      - `size` integer, required: File size in bytes.
      - `metadata` object: Optional metadata about the file.
        - `original_filename` string: Original filename before upload.
    - `file_id` string, required: Accepted file_id returned by /shipments/documents. Use instead of file.

## Response `200`

An object representing the Shipment.

- ShipmentObject
  - `id` string: Unique identifier of the Shipment.
  - `merchant_invoice_id` string: ID of the associated merchant invoice.
  - `fulfillment_method` 'shipping_provider' | 'self_delivery' | 'customer_pickup' | 'services_only': Method of fulfillment for the shipment.
  - `shipment_tracking_number` string: Tracking number provided by the shipping courier.
  - `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.
  - `verification_status` 'verified' | 'pending': Manual or automatic verification status of the shipment.
  - `created_at` string, date-time: Date time when the shipment was created.
  - `updated_at` string, date-time: Date time when the shipment was last updated.
  - `tracking_status` string, nullable: Current tracking status of the shipment from the courier.
  - `tracking_substatus` string, nullable: Detailed tracking substatus providing additional context about the shipment's current state.
  - `expected_delivery` string, date-time, nullable: Expected delivery date and time provided by the shipping courier.

## Other responses

- `400`: Bad request error
- `401`: Unauthorized error
- `404`: Not found error
- `429`: Rate limit error

---

[API](https://skmtc.dev/resolvepay/apis/resolve-api-reference.md) - [All operations](https://skmtc.dev/resolvepay/apis/resolve-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/resolvepay/apis/resolve-api-reference/revisions/c62edc454aaa?raw)