API Changelog

API Environments

• Production: https://api.piyovi.io
• Sandbox: https://apiuat.piyovi.io — test integrations using the API Sandbox.

For complete endpoint documentation, see the API Reference.

v26.08.01

User Preference API — Bulk Retrieval

The User Preference API now supports retrieving shipment preferences for multiple users in a single request.

Method	Endpoint
POST	/v1/preference/user/shipment
Supported Options
Property	Description
---	---
pageNumber	Page number to retrieve
pageSize	Number of records per page
filter	Filter user preferences by User Reference ID

Filtering

User preferences can be filtered using UserId with the In condition, allowing multiple User Reference IDs to be provided in a single request.

This reduces the number of API calls required when integrations need preference information for multiple users.

Shipment Search API — Surcharge Details

The Shipment Search API response now includes shipment surcharge details as part of the Billing Details.

Method	Endpoint
POST	/v1/shipment/search
What's New
When surcharge information is available for a shipment, it is now returned under the surcharges section within Billing Details.
Behavior

• If the shipment has surcharge details, they are included in the response.

• If no surcharge details are available, the surcharges section remains empty.

• No changes are required to existing Shipment Search API requests.

This allows integrations to retrieve shipment and surcharge information together in a single API response.

v26.06.01

Overview

This release introduces new APIs for Carrier Management, Company and User Preferences, Rate Shop Rules, and Consolidation Rules. It also enhances existing Shipment APIs by adding support for Rate Shop Details and Shipment Custom Attributes.

New APIs

Carrier Management APIs

Manage carrier accounts, carriers, tracking configurations, and rate configurations.

Method	Endpoint	Description
POST	/v1/carrier/accounts	Retrieve all carrier accounts
GET	/v1/carrier/account/{id}	Retrieve a carrier account by ID
POST	/v1/carriers	Retrieve all carriers
GET	/v1/carrier/{id}	Retrieve a carrier by ID
GET	/v1/carrier/tracking/{type}	Retrieve tracking configuration
GET	/v1/carrier/rate/{type}	Retrieve rate configuration

Supported Tracking Types

• manual_entry
• number_range
• auto

Supported Rate Types

• manual_entry
• rate_files
• none

Activities API

Retrieve organization-level activities.

Method	Endpoint
POST	/v1/activities

Company Preference APIs

Retrieve and update company preferences.

Preference	GET	POST
Shipment Preferences	/v1/preference/company/shipment	/v1/preference/company/shipment
Notification Preferences	/v1/preference/company/notification	/v1/preference/company/notification
User Policy Preferences	/v1/preference/company/user_policy	/v1/preference/company/user_policy

User Preference APIs

Retrieve and update shipment preferences for the current user.

Method	Endpoint
GET	/v1/preference/user/shipment
POST	/v1/preference/user/shipment

User preferences automatically inherit company defaults for settings that are not explicitly configured.

Rate Shop Rules APIs

Create and manage Rate Shop Rules.

Method	Endpoint	Action
GET	/v1/rule/rateshop	List
POST	/v1/rule/rateshop	Create
GET	/v1/rule/rateshop/{id}	Retrieve
PUT	/v1/rule/rateshop/{id}	Update
DELETE	/v1/rule/rateshop/{id}	Delete

Consolidation Rules APIs

Create and manage Consolidation Rules.

Method	Endpoint	Action
POST	/v1/rule/consolidations	List
POST	/v1/rule/consolidation	Create
GET	/v1/rule/consolidation/{id}	Retrieve
PUT	/v1/rule/consolidation/{id}	Update
DELETE	/v1/rule/consolidation/{id}	Delete

API Enhancements

Shipment Search API — Rate Shop Details

The Shipment Search API now supports returning Rate Shop Details.

Method	Endpoint
POST	/v1/shipment/search

New Request Property

Property	Type	Default
additionalOptions.IncludeRateShop	Boolean	false

When enabled, the response includes Rate Shop comparison details together with standard shipment data.

Shipment Update API — Custom Attributes

The Shipment Update API now supports updating shipment-level custom attributes.

Method	Endpoint
POST	/v1/shipment/update

New Request Property

Property	Type
customAttributes	Object

Rules

• Keys must use the configured System Name.
• Values must be strings.
• Only shipment-level custom attributes are supported.

v26.05.01

Overview

This release enhances the Rate API with service level filtering, adds a Shipment Consolidation API with webhook support, and extends Shipment APIs with manual billing details and custom properties in responses and webhooks.

New APIs

Shipment Consolidation API

The Headless Shipment API now supports external shipment consolidation directly through API, eliminating the need to manually consolidate shipments from the Piyovi UI.

External systems such as ERP, WMS, and OTM platforms can automatically create consolidated shipments, group existing shipments, apply consolidation rules, and receive webhook notifications when rules are applied.

Method	Endpoint	Description
POST	/v1/shipment/consolidation	Consolidate shipments through external API

Capabilities

• Creating a master shipment with child shipments
• Consolidating existing shipments directly through API
• Applying consolidation rules during processing
• Triggering webhooks when shipment rules are applied
• Returning consolidation details and unmatched shipments in the response

Supported Child Shipment Lookup Methods

Lookup Type	Description
Shipment_Id	Piyovi shipment delivery number
ReferenceNumber	External integration reference number
ReferenceType + ReferenceNumber	Combination lookup for duplicate references
ReferenceFields	Custom shipment reference fields such as PO Number or BOL

New Request Properties

Property	Type
additionalOptions.applyRule	Boolean
additionalOptions.ruleIndicator	String

Behavior

• With applyRule = true: The system validates and applies the specified consolidation rule during processing.
• With a valid rule indicator: The matching consolidation rule is identified and executed automatically.
• Without a rule indicator: Consolidation continues without rule-based processing.
• With applyRule = false: Shipments are consolidated normally without applying any consolidation rule.
• With existing shipments only: If only existing shipment identifiers are provided, the first shipment automatically becomes the master shipment.

Webhook Enhancement

A new webhook event is triggered whenever shipment or consolidation rules are applied.

Event Name	Trigger
shipment.rule.applied	When shipment or consolidation rules are applied

Webhook Payload Includes

• Rule information
• Shipment information
• Rule result details
• Package details
• Shipment references
• Carrier and service-level information

Webhook Behavior

• Webhooks are triggered for external shipment API processing, consolidation API processing, shipment processing from the Piyovi UI, and milestone import rule processing.
• Webhook delivery failures do not block shipment processing or consolidation execution.

Validation Rules

• Only shipments in draft status can be consolidated.
• A shipment already acting as a master shipment cannot be consolidated again.
• A shipment cannot exist as both master and child in the same request.
• Duplicate shipment references in the same request are rejected.
• If applyRule is enabled but the rule is not found, the request fails with a validation error.

Notes

• Existing shipment webhooks continue to function without changes.
• Webhook payloads include full shipment details to reduce additional API lookups.
• Consolidation behavior in the Piyovi UI remains unchanged.

API Enhancements

Rate API — Service Level Filtering

The Headless Rate Shop API now supports Service Level Filtering, allowing integrations to include or exclude specific carrier services during rate shopping.

Method	Endpoint
POST	/v1/shipment/rate

New Request Properties

Property	Type
rateShopOptions.filters.includedServices	Array of Strings
rateShopOptions.filters.excludedServices	Array of Strings

Service Format

Service values must be provided in the following format:

CarrierName-ServiceReferenceUID

Example

"includedServices": ["DHL-DHL DOMESTIC EXPRESS"],
"excludedServices": null

Behavior

• includedServices returns only the specified services.
• excludedServices excludes specified services from the response.
• If no service filters are provided, all eligible services are returned.
• Service filters work together with existing carrier filters.

Notes

• includedServices and excludedServices cannot both contain values in the same request.
• Carrier matching is case-insensitive.
• Blank entries are ignored automatically.
• Invalid carrier/service combinations return validation errors.

External Shipment API — Manual Entry Billing Details

The External Shipment API now supports manual entry of billing details for shipments using carriers configured with the Manual Entry Rate Method.

Method	Endpoint
POST	/v1/shipment

New Request Property

Property	Type
billingDetail	Object

Billing Detail Object

Property	Description
estimatedDelivery	Estimated shipment delivery date and time
baseCharge	Base transportation charge
totalSurcharges	Total surcharge amount
totalFreight	Total freight amount
currencyCode	Currency code for billing amounts

Behavior

• With Manual Entry carriers: Billing details provided in the payload are saved with the shipment.
• Without billing details: The shipment is still created successfully.
• With non-manual carriers: Billing details are ignored.
• Existing shipment processing: All other shipment functionality remains unchanged.

Shipment Response & Webhook — Custom Properties Support

Shipment responses and webhook payloads now support carrier-specific response values under a dedicated customProperties object.

Location	Property	Type
Shipment Response & Webhook Payload	customProperties	Object

This enhancement applies to shipment responses and shipment-related webhook events.

Behavior

• Shipment processing: Carrier response values are automatically captured under customProperties.
• Shipment responses: Carrier-specific values are returned in a structured format.
• Webhook payloads: The same customProperties structure is included across shipment-related webhook events.
• Existing functionality: Existing shipment and webhook behavior remains unchanged.

Benefits

• Cleaner and more organized payload structure
• Easier handling of carrier-specific response data
• Improved consistency across shipment responses and webhooks
• Simplified downstream integration processing

v26.04.01

Overview

This release enhances the Shipment Search API with tracking URLs and adds support for importing externally processed shipments through the Headless Shipment API.

API Enhancements

Shipment Search API — Tracking URL

The Shipment Search API now includes the Tracking URL in the response payload, enabling external systems and users to directly access carrier tracking pages without additional integrations or manual lookup.

Method	Endpoint
POST	/v1/shipment/search

New Response Property

Property	Type
trackingUrl	String

Behavior

• With supported carriers: If the carrier provides tracking details, the API returns a valid trackingUrl for the shipment.
• With generic carriers: Tracking URL will not be available, as generic carriers do not provide tracking details.
• Existing behavior: All other shipment response fields remain unchanged.

Headless Shipment API — External Shipment Import

The Headless Shipment API now supports importing shipments that are processed outside of Piyovi, allowing external systems (ERP, WMS, or third-party platforms) to push shipment data into Piyovi for centralized visibility, reporting, and downstream processing.

Method	Endpoint
POST	/v1/shipment

New Request Property

Property	Type
action	String (Import)

Behavior

• For external shipments: Set the action field to Import to treat the request as external shipment ingestion.
• Data handling: Imported shipments are stored and made available within Piyovi for tracking, reporting, and operational workflows.
• Without import action: The API follows the standard shipment creation flow within Piyovi.

Notes

• For the correct shipment payload structure and required fields, refer to the API Reference.

v26.03.01

Overview

This release enhances the Rate API with Rate Shop Options, allowing external integrations to apply dynamic filtering at the API level for more precise rate results.

API Enhancements

Rate API — Rate Shop Options

The Rate API now supports Rate Shop Options within the request payload. Rate results are filtered before being returned, eliminating the need for additional post-processing.

Method	Endpoint
POST	/v1/shipment/rate

New Request Property

Property	Type
rateShopOptions.filters	Object

Filter Object

Property	Description
includedCarriers	List of carriers to include in rate results (Carrier Name or SCAC)
excludedCarriers	List of carriers to exclude from rate results
accounts	Specific carrier accounts to be used for rate calculation
autoSelect	Auto-selection logic (cheapest or fastest)

Behavior

• With filters provided: The API returns only the rates that match the specified carriers, services, and accounts. If autoSelect is provided, the system automatically selects the best option based on the given criteria.
• Without filters: The API returns all available rate options as per existing behavior or configured Rate Shop Rules.
• With existing Rate Shop Rules: Filters can be used alongside configured rules, depending on business requirements.

v26.02.01

Overview

This release enhances the Headless Shipment API to accept documents directly within the shipment creation payload.

API Enhancements

Headless Shipment API — Document Support

The Headless Shipment API now supports accepting documents directly within the shipment creation payload, allowing external integrations to attach shipment-related documents during shipment creation without requiring a separate document upload API.

Method	Endpoint
POST	/v1/shipment

New Request Property

Property	Type
documents[]	Array of document objects

Document Object

Property	Description
documentName	Name of the document file
documentType	Document type identifier
documentContentType	Content format (e.g., BASE64)
documentContent	Base64 encoded document content

Behavior

• With documents provided: The API decodes the Base64 document content, stores the document, and links it to the created shipment.
• Without documents: Shipment creation behavior remains unchanged.
• Multiple documents: The API supports submitting multiple documents in the documents[] array within the same shipment request.