Create Shipment API

Try Now

POST https://api.piyovi.io/v1/shipment

Overview

The Create Shipment API allows you to create a new shipment in the Piyovi system. This endpoint handles all necessary shipment details including origin, destination, package information, and any special requirements.

Authentication

This API requires authentication using one of the following methods:

Bearer Token: Include JWT with Bearer prefix in the Authorization header
API Key: Include X-API-KEY header with your API key

For more details, see Authentication Guide.

Request Format

POST /v1/shipment
Content-Type: application/json
Authorization: Bearer {token}

Request Body

{
  "client": "MyClient",
  "location": "MainWarehouse",
  "shipDate": "2025-03-20T14:00:00Z",
  "shipTo": {
    "companyName": "Example Corp",
    "contactName": "John Doe",
    "emailAddress": "john@example.com",
    "phoneNumber1": "123-456-7890",
    "address1": "123 Main St",
    "city": "San Francisco",
    "stateProvince": "CA",
    "country": "US",
    "zipPostalCode": "94105"
  },
  "shipFrom": {
    "companyName": "Your Company",
    "contactName": "Jane Smith",
    "emailAddress": "jane@yourcompany.com",
    "phoneNumber1": "987-654-3210",
    "address1": "456 Warehouse Blvd",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  },
  "shipmentInfo": {
    "shipMethod": "Ground",
    "carrier": "FedEx",
    "serviceLevel": "Standard"
  },
  "packages": [
    {
      "weight": 25.5,
      "length": 20,
      "width": 15,
      "height": 10,
      "type": "Box",
      "declaredValue": 500,
      "items": [
        {
          "itemId": "ITEM-123",
          "name": "Product Sample",
          "description": "Product samples for marketing",
          "weight": 25.5,
          "qty": 5,
          "unitPrice": 100
        }
      ]
    }
  ],
  "references": {
    "orderNumber": "ORD-12345",
    "customerPO": "PO-6789"
  }
}

Response Format

Success Response (200 OK)

{
  "success": true,
  "id": "ship-12345678",
  "shipmentReference": "FDX-987654321",
  "status": "Created",
  "trackingNumber": "794612345678",
  "activity_Id": "act-12345",
  "estimatedDelivery": "2025-03-23T17:00:00Z",
  "transitDays": "3",
  "carrierAccount": "FDX-ACCOUNT",
  "carrierServiceLevel": "GROUND",
  "carrier": "FedEx",
  "shipMethod": "Ground",
  "references": {
    "orderNumber": "ORD-12345",
    "customerPO": "PO-6789"
  },
  "packages": [
    {
      "package_Id": "pkg-123456",
      "referenceId": "0",
      "weight": 25.5,
      "length": 20,
      "width": 15,
      "height": 10,
      "trackingNumber": "794612345678",
      "type": "Box",
      "unitOfLength": "IN",
      "unitOfWeight": "LB",
      "count": 1
    }
  ],
  "billingDetail": {
    "totalFreight": 45.67,
    "totalDiscountFreight": 41.10,
    "baseCharge": 39.99,
    "totalSurcharges": 5.68,
    "totalTaxes": 0.00,
    "currencyCode": "USD"
  },
  "documents": [
    {
      "document_Id": "doc-12345",
      "documentName": "Shipping Label",
      "documentType": "Label",
      "documentContentType": "application/pdf",
      "documentContent": "BASE64_ENCODED_CONTENT",
      "documentMimeType": "application/pdf"
    }
  ],
  "trackingUrl": "https://www.fedex.com/track?trknbr=794612345678"
}

Error Response (400 Bad Request)

{
  "success": false,
  "errors": [
    {
      "code": "InvalidAddress",
      "message": "Destination address could not be validated",
      "type": "ValidationError"
    }
  ]
}

Field Reference

Field	Type	Required	Description
client	string	No	Client identifier
location	string	No	Location identifier
shipDate	datetime	Yes	Date and time when the shipment will be sent
shipTo	object	Yes	Destination address details
shipFrom	object	Yes	Origin address details
shipmentInfo	object	Yes	Shipping method and carrier preferences
packages	array	Yes	Array of package details
references	object	No	Custom reference fields
internationalDetail	object	No	International shipping information (required for international shipments)
notes	string	No	Special instructions or notes for the shipment
unitOfWeight	string	No	Unit of measurement for weight (e.g., KG, LB)
unitOfLength	string	No	Unit of measurement for dimensions (e.g., CM, IN)
dgItems	array	No	Dangerous goods details (if applicable)
additionalOptions	object	No	Additional options for the shipment

Address Object Fields (shipTo, shipFrom)

Field	Type	Required	Description
companyName	string	No	Company name
contactName	string	No	Contact person's name
emailAddress	string	No	Email address
phoneNumber1	string	No	Primary phone number
address1	string	Yes	Street address line 1
address2	string	No	Street address line 2
city	string	Yes	City name
stateProvince	string	Yes	State or province
country	string	Yes	Country code (2-letter ISO code recommended)
zipPostalCode	string	Yes	Postal or ZIP code

Shipment Info Object Fields

Field	Type	Required	Description
shipMethod	string	Yes	Method of shipment (e.g., Ground, Express)
carrier	string	Yes	Carrier name
serviceLevel	string	No	Service level
carrierAccount	string	No	Carrier account identifier
paymentType	string	No	Payment method (e.g., Prepaid, Collect)

Package Object Fields

Field	Type	Required	Description
weight	number	Yes	Weight of the package
length	number	Yes	Length of the package
width	number	Yes	Width of the package
height	number	Yes	Height of the package
type	string	No	Type of package (e.g., Box, Pallet)
declaredValue	number	No	Declared value for insurance
items	array	No	Array of items in the package

Examples

Basic Domestic Shipment

{
  "client": "ExampleClient",
  "location": "DefaultWarehouse",
  "shipDate": "2025-03-20T14:00:00Z",
  "shipTo": {
    "companyName": "Recipient Corp",
    "contactName": "John Recipient",
    "address1": "123 Delivery St",
    "city": "Los Angeles",
    "stateProvince": "CA",
    "country": "US",
    "zipPostalCode": "90001"
  },
  "shipFrom": {
    "companyName": "Sender Inc",
    "contactName": "Jane Sender",
    "address1": "456 Shipping Ave",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  },
  "shipmentInfo": {
    "shipMethod": "Ground",
    "carrier": "UPS"
  },
  "packages": [
    {
      "weight": 10.5,
      "length": 12,
      "width": 8,
      "height": 6,
      "type": "Box"
    }
  ]
}

International Shipment with Multiple Packages

{
  "client": "GlobalClient",
  "location": "ExportWarehouse",
  "shipDate": "2025-03-25T10:00:00Z",
  "shipTo": {
    "companyName": "International Corp",
    "contactName": "Hans Importer",
    "address1": "123 Global Street",
    "city": "Berlin",
    "stateProvince": "Berlin",
    "country": "DE",
    "zipPostalCode": "10115"
  },
  "shipFrom": {
    "companyName": "Exporter Inc",
    "contactName": "Maria Exporter",
    "address1": "789 Export Road",
    "city": "New York",
    "stateProvince": "NY",
    "country": "US",
    "zipPostalCode": "10001"
  },
  "shipmentInfo": {
    "shipMethod": "Express",
    "carrier": "DHL",
    "serviceLevel": "International Express"
  },
  "packages": [
    {
      "weight": 5.2,
      "length": 15,
      "width": 10,
      "height": 8,
      "type": "Box",
      "declaredValue": 250
    },
    {
      "weight": 7.8,
      "length": 20,
      "width": 12,
      "height": 10,
      "type": "Box",
      "declaredValue": 350
    }
  ],
  "internationalDetail": {
    "dutiesPaidBy": "Sender",
    "totalCustomValue": 600,
    "reasonToExport": "Commercial Sample",
    "incoTerm1": "DAP",
    "currencyCode": "USD",
    "commodities": [
      {
        "description": "Product Samples",
        "numberOfBoxes": 2,
        "quantity": 10,
        "unitWeight": 1.3,
        "unitPrice": 60,
        "customValue": 600,
        "countryOfOrigin": "US"
      }
    ]
  }
}

Notes

For international shipments, ensure you provide all required customs information in the internationalDetail object.
For dangerous goods, include detailed information in the dgItems array.
The response will include tracking information and shipping documents (labels) in base64 format.
Use the references object to include your own reference information (e.g., order numbers, PO numbers).

Try Now​

Overview​

Authentication​

Request Format​

Request Body​

Response Format​

Success Response (200 OK)​

Error Response (400 Bad Request)​

Field Reference​

Address Object Fields (shipTo, shipFrom)​

Shipment Info Object Fields​

Package Object Fields​

Examples​

Basic Domestic Shipment​

International Shipment with Multiple Packages​

Notes​