Shipment APIs

This page provides documentation for the various shipment-related APIs available in the Piyovi platform. These APIs allow you to manage shipments throughout their lifecycle.

Authentication

All APIs require authentication using either API Key or OAuth 2.0 Bearer Token. For details, see Authentication Guide.

Shipment APIs Overview

API	Method	Endpoint	Description
Create Shipment	POST	/v1/shipment	Create a new shipment
Rate Shop	POST	/v1/shipment/rate	Get shipping rates from multiple carriers
Address Validation	POST	/v1/shipment/address_validation	Validate and standardize addresses
Cancel Shipment	POST	/v1/shipment/cancel	Cancel an existing shipment
Search Shipments	POST	/v1/shipments	Search shipments with pagination and filtering
Update Shipment	POST	/v1/shipment/update	Update an existing shipment
Track Shipment	POST	/v1/shipment/track	Get tracking information for shipments
Block Shipment	PUT	/v1/shipment/{id}/block	Block a shipment from being processed
Unblock Shipment	PUT	/v1/shipment/{id}/unblock	Unblock a previously blocked shipment
Archive Shipment	DELETE	/v1/shipment/{id}/archive	Archive a shipment
Apply Business Rule	POST	/v1/shipment/apply_rule	Apply business rules to a shipment

Cancel Shipment

Endpoint

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

Request Format

{
  "shipments": [
    {
      "id": "ship-12345678",
      "cancelReason": "Customer request"
    },
    {
      "id": "ship-87654321",
      "cancelReason": "Inventory issue"
    }
  ]
}

Response Format

{
  "success": true,
  "shipments": [
    {
      "success": true,
      "shipment_Id": "ship-12345678",
      "activity_Id": "act-12345",
      "status": "Cancelled",
      "trackingNumber": "794612345678"
    },
    {
      "success": true,
      "shipment_Id": "ship-87654321",
      "activity_Id": "act-54321",
      "status": "Cancelled",
      "trackingNumber": "794687654321"
    }
  ]
}

Search Shipments

Endpoint

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

Request Format

{
  "pageNumber": 1,
  "pageSize": 10,
  "searchTerm": "Chicago",
  "filter": [
    {
      "column": "shipmentDate",
      "condition": 3,
      "value": "2025-03-01T00:00:00Z"
    },
    {
      "column": "statusId",
      "condition": 0,
      "value": "Created"
    }
  ],
  "orderdBy": [
    {
      "column": "shipmentDate",
      "direction": "DESC"
    }
  ]
}

Response Format

{
  "success": true,
  "shipments": [
    {
      "id": "ship-12345678",
      "shipmentId": "FDX-987654321",
      "statusId": "Created",
      "shipmentDate": "2025-03-15T14:00:00Z",
      "locationName": "MainWarehouse",
      "totalPackage": 1,
      "totalPackageWeight": "25.5 LB",
      "shipFrom": { /* address details */ },
      "shipTo": { /* address details */ },
      "shipmentInfo": { /* shipment info details */ },
      "trackingUrl": "https://www.fedex.com/track?trknbr=794612345678"
    },
    /* more shipment objects */
  ],
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 35,
  "totalPages": 4,
  "hasPreviousPage": false,
  "hasNextPage": true
}

Update Shipment

Endpoint

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

Request Format

{
  "shipments": [
    {
      "id": "ship-12345678",
      "carrierReferenceId": "FDX-987654321",
      "shipMethod": "Express",
      "references": {
        "orderNumber": "ORD-12345-UPDATED",
        "customerPO": "PO-6789-UPDATED"
      },
      "discountedCost": 39.99
    }
  ]
}

Response Format

{
  "shipments": [
    {
      "success": true,
      "shipment_Id": "ship-12345678",
      "message": "Shipment updated successfully"
    }
  ]
}

Track Shipment

Endpoint

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

Request Format

{
  "shipments": [
    {
      "trackingNumber": "794612345678"
    },
    {
      "id": "ship-87654321"
    }
  ]
}

Response Format

{
  "success": true,
  "shipments": [
    {
      "success": true,
      "tracking_Id": "trk-12345",
      "shipment_Id": "ship-12345678",
      "trackingNumber": "794612345678",
      "lastUpdateOnUtc": "2025-03-17T12:30:45Z",
      "events": [
        {
          "carrierCode": "FDX",
          "code": "OD",
          "exception": false,
          "description": "Out for Delivery",
          "eventOn": "2025-03-17T08:15:22Z",
          "city": "Los Angeles",
          "state": "CA",
          "country": "US",
          "zipCode": "90001"
        },
        {
          "carrierCode": "FDX",
          "code": "AR",
          "exception": false,
          "description": "Arrived at FedEx location",
          "eventOn": "2025-03-16T22:45:10Z",
          "city": "Los Angeles",
          "state": "CA",
          "country": "US",
          "zipCode": "90001"
        }
      ],
      "trackingUrl": "https://www.fedex.com/track?trknbr=794612345678"
    },
    /* second shipment tracking details */
  ]
}

Block Shipment

Endpoint

PUT https://api.piyovi.io/v1/shipment/{id}/block

Request Format

{
  "reason": "Payment issue"
}

Response Format

{
  "success": true,
  "message": "Shipment ship-12345678 has been blocked"
}

Unblock Shipment

Endpoint

PUT https://api.piyovi.io/v1/shipment/{id}/unblock

Request Format

{
  "reason": "Payment received"
}

Response Format

{
  "success": true,
  "message": "Shipment ship-12345678 has been unblocked"
}

Archive Shipment

Endpoint

DELETE https://api.piyovi.io/v1/shipment/{id}/archive

Response Format

{
  "success": true,
  "message": "Shipment ship-12345678 has been archived"
}

Apply Business Rule

Endpoint

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

Request Format

The request format is the same as the Create Shipment API.

Response Format

{
  "success": true,
  "ruleId": "rule-12345",
  "ruleName": "Premium Customer Rule",
  "carrierAccount": "FDX-PREMIUM",
  "specialService": "SATURDAY_DELIVERY",
  "shipMethod": "EXPRESS",
  "instructions": "Handle with care - Premium customer",
  "parties": [
    {
      "party": "SHIPPER",
      "companyName": "Your Company",
      "address1": "456 Warehouse Blvd",
      "city": "Chicago",
      "stateProvince": "IL",
      "country": "US",
      "zipPostalCode": "60601"
    }
  ]
}

Error Handling

All APIs follow a consistent error response format:

{
  "success": false,
  "errors": [
    {
      "code": "InvalidRequest",
      "message": "Detailed error message",
      "type": "ValidationError"
    }
  ]
}

Common error codes include:

Error Code	Description
InvalidRequest	The request format is invalid
ShipmentNotFound	The specified shipment was not found
AddressValidationFailed	The address could not be validated
RateRequestFailed	Unable to obtain rates
AuthenticationFailed	Authentication credentials are invalid
PermissionDenied	User does not have permission for the requested action

Rate Limits

• Standard tier: 100 requests per minute
• Premium tier: 500 requests per minute
• Enterprise tier: Custom rate limits based on contract

When rate limits are exceeded, the API will return a 429 Too Many Requests status code.

Best Practices

1. Validate Addresses: Always validate addresses before creating shipments
2. Batch Processing: Use batch endpoints where possible to reduce API calls
3. Error Handling: Implement proper error handling in your application
4. Caching: Cache frequently used data (e.g., rates for common routes)
5. Webhooks: Consider using webhooks for tracking updates instead of polling