Skip to content

Create a Shipment

Request

Security
bearerAuth or basicAuth
Bodyapplication/jsonrequired

Request body for creating a new shipment.

One of:
merchant_invoice_idstringrequired

ID of the merchant invoice this shipment belongs to.

Example:"inv_1234567890abcdef"
fulfillment_methodstring

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.
Default:"shipping_provider"
Value:"shipping_provider"
Example:"shipping_provider"
shipment_tracking_numberstringrequired

Tracking number (required when fulfillment_method is shipping_provider, optional otherwise).

Example:"1Z123E45678901234"
shipment_courierstringrequired

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 for the complete list of supported couriers.

Example:"ups"
send_emailboolean

Whether to send the buyer an invoice updated email.

Default:true
fileobject(ShipmentFile)

Proof of delivery file. Required for self_delivery, customer_pickup, and services_only fulfillment methods. Forbidden for shipping_provider fulfillment method.

For the validation-backed flow, use /shipments/documents, wait for acceptance, then provide file_id instead.

Example:
{ "url": "https://bucket.s3.amazonaws.com/1234567890-document.pdf", "size": 204800, "metadata": { "original_filename": "proof_of_delivery.pdf" } }
file_idstring

Accepted file_id returned by /shipments/documents. Use instead of file.

curl -i -X POST \
  https://docs.resolvepay.com/_mock/merchant-api/openapi/shipments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fulfillment_method": "shipping_provider",
    "shipment_tracking_number": "1Z123E45678901234",
    "shipment_courier": "ups",
    "merchant_invoice_id": "inv_1234567890abcdef",
    "send_email": true,
    "file": {
      "url": "https://bucket.s3.amazonaws.com/1234567890-document.pdf",
      "size": 204800,
      "metadata": {
        "original_filename": "proof_of_delivery.pdf"
      }
    },
    "file_id": "string"
  }'

Responses

An object representing the Shipment.

Bodyapplication/json
idstring

Unique identifier of the Shipment.

Example:"ship_1234567890abcdef"
merchant_invoice_idstring

ID of the associated merchant invoice.

Example:"inv_1234567890abcdef"
fulfillment_methodstring

Method of fulfillment for the shipment.

Enum:"shipping_provider""self_delivery""customer_pickup""services_only"
Example:"shipping_provider"
shipment_tracking_numberstring

Tracking number provided by the shipping courier.

Example:"1Z123E45678901234"
shipment_courierstring

Shipping courier or provider name. While any value can be accepted, instant verification is supported for specific couriers.

See the Shipments API documentation for the complete list of supported couriers.

Example:"ups"
verification_statusstring

Manual or automatic verification status of the shipment.

Enum:"verified""pending"
Example:"verified"
created_atstring, (date-time)

Date time when the shipment was created.

Example:"2024-01-15T10:30:00Z"
updated_atstring, (date-time)

Date time when the shipment was last updated.

Example:"2024-01-15T14:45:00Z"
tracking_statusstring or null

Current tracking status of the shipment from the courier.

Example:"delivered"
tracking_substatusstring or null

Detailed tracking substatus providing additional context about the shipment's current state.

Example:"delivered_001"
expected_deliverystring or null, (date-time)

Expected delivery date and time provided by the shipping courier.

Example:"2024-01-20T18:00:00Z"
Response
{ "id": "ship_1234567890abcdef", "merchant_invoice_id": "inv_1234567890abcdef", "fulfillment_method": "shipping_provider", "shipment_tracking_number": "1Z123E45678901234", "shipment_courier": "ups", "verification_status": "verified", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T14:45:00Z", "tracking_status": "delivered", "tracking_substatus": "delivered_001", "expected_delivery": "2024-01-20T18:00:00Z" }