Location

This page provides documentation for the location-related APIs available in the Piyovi platform. These APIs allow you to manage shipping locations for your organization.

Authentication

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

Location APIs Overview

API	Method	Endpoint	Description
Get Locations	GET	/v1/locations	Retrieve a list of locations with pagination and filtering
Get Location	GET	/v1/location/{id}	Get detailed information about a specific location
Create Location	POST	/v1/location	Create a new location
Update Location	PUT	/v1/location/{id}	Update an existing location
Delete Location	DELETE	/v1/location/{id}	Delete a location

Get Locations

Endpoint

GET https://api.piyovi.io/v1/locations

Parameters

Parameter	Type	Required	Description
Query	string	No	Search term to filter locations
Page	integer	Yes	Page number (1-based)
Limit	integer	Yes	Number of items per page
Sort	string	No	Field to sort by (e.g., locationName)
Order	string	No	Sort direction (ASC or DESC)

Example Request

GET https://api.piyovi.io/v1/locations?Page=1&Limit=10&Query=warehouse&Sort=locationName&Order=ASC

Response Format

{
  "success": true,
  "data": [
    {
      "id": "loc-123456",
      "referenceId": "MAIN-WH",
      "groupId": "group-123",
      "locationName": "Main Warehouse",
      "emailAddress": "warehouse@example.com",
      "address1": "123 Warehouse Blvd",
      "city": "Chicago",
      "stateProvince": "IL",
      "defaultDescription": ["Consumer Electronics", "Retail Products"],
      "contactName": "John Smith",
      "country": "US",
      "zipPostalCode": "60601",
      "phoneNumber1": "312-555-1234",
      "active": true,
      "deleted": false,
      "createdBy": "user@example.com",
      "createdOnUtc": "2025-01-15T10:30:00Z",
      "updatedBy": "user@example.com"
    },
    /* more location objects */
  ],
  "pageNumber": 1,
  "pageSize": 10,
  "totalCount": 25,
  "totalPages": 3,
  "hasPreviousPage": false,
  "hasNextPage": true
}

Get Location

Endpoint

GET https://api.piyovi.io/v1/location/{id}

Example Request

GET https://api.piyovi.io/v1/location/loc-123456

Response Format

{
  "success": true,
  "id": "loc-123456",
  "referenceId": "MAIN-WH",
  "groupId": "group-123",
  "locationName": "Main Warehouse",
  "emailAddress": "warehouse@example.com",
  "altEmailAddress": "wh-backup@example.com",
  "faxNumber": "312-555-9876",
  "phoneNumber1": "312-555-1234",
  "phoneNumber2": "312-555-5678",
  "active": true,
  "address": {
    "contactName": "John Smith",
    "emailAddress": "john@example.com",
    "phoneNumber1": "312-555-1234",
    "address1": "123 Warehouse Blvd",
    "address2": "Building A",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  },
  "billingAddress": {
    "contactName": "Finance Department",
    "emailAddress": "finance@example.com",
    "phoneNumber1": "312-555-4321",
    "address1": "789 Corporate Pkwy",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60602"
  },
  "settings": {
    "currencyCode": "USD",
    "unitOfWeight": "LB",
    "unitOfLength": "IN",
    "defaultTimezone": "America/Chicago",
    "manualShippingAvailable": true,
    "defaultDescription": ["Consumer Electronics", "Retail Products"],
    "defaultDeclaration": "Commercial Samples"
  },
  "dgDetail": {
    "emergPhone": "800-555-1234",
    "offererContractHolder": "John Smith",
    "contractNo": "DG-12345"
  },
  "regionalSetting": {
    "useItemData": true,
    "defaultFreightClass": "70",
    "defaultNmfcCode": "123456",
    "autoCalcFreightClass": true,
    "zeroFreightforOutboundThirdParty": false,
    "zeroFreightforOutboundCollectOrRecipient": false
  },
  "tags": ["warehouse", "electronics", "midwest"]
}

Create Location

Endpoint

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

Request Format

{
  "referenceId": "EAST-WH",
  "groupId": "group-123",
  "locationName": "East Coast Warehouse",
  "active": true,
  "address": {
    "contactName": "Sarah Johnson",
    "emailAddress": "sarah@example.com",
    "phoneNumber1": "212-555-1234",
    "address1": "456 Storage Ave",
    "city": "New York",
    "stateProvince": "NY",
    "country": "US",
    "zipPostalCode": "10001"
  },
  "billingAddress": {
    "contactName": "Finance Department",
    "emailAddress": "finance@example.com",
    "phoneNumber1": "212-555-4321",
    "address1": "789 Corporate Pkwy",
    "city": "New York",
    "stateProvince": "NY",
    "country": "US",
    "zipPostalCode": "10002"
  },
  "settings": {
    "currencyCode": "USD",
    "unitOfWeight": "LB",
    "unitOfLength": "IN",
    "defaultTimezone": "America/New_York",
    "manualShippingAvailable": true,
    "defaultDescription": ["Industrial Equipment", "Spare Parts"]
  },
  "regionalSetting": {
    "useItemData": true,
    "defaultFreightClass": "65",
    "autoCalcFreightClass": true
  },
  "tags": ["warehouse", "industrial", "east-coast"]
}

Response Format

{
  "success": true,
  "id": "loc-789012",
  "referenceId": "EAST-WH"
}

Update Location

Endpoint

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

Request Format

The request format is the same as the Create Location API. You only need to include the fields you want to update.

Example Request

PUT https://api.piyovi.io/v1/location/loc-123456
Content-Type: application/json

{
  "locationName": "Main Warehouse - Updated",
  "active": true,
  "address": {
    "phoneNumber1": "312-555-9999",
    "address1": "123 Warehouse Blvd",
    "address2": "Building B",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  },
  "settings": {
    "defaultDescription": ["Consumer Electronics", "Retail Products", "Household Goods"]
  }
}

Response Format

{
  "success": true,
  "id": "loc-123456",
  "referenceId": "MAIN-WH"
}

Delete Location

Endpoint

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

Example Request

DELETE https://api.piyovi.io/v1/location/loc-123456

Response Format

{
  "success": true,
  "id": "loc-123456",
  "referenceId": "MAIN-WH"
}

Field Reference

Location Object Fields

Field	Type	Required	Description
referenceId	string	Yes	Your reference identifier for the location
groupId	string	No	Group identifier for organizing locations
locationName	string	Yes	Name of the location
active	boolean	Yes	Whether the location is active
address	object	Yes	Physical address of the location
billingAddress	object	No	Billing address (if different from physical address)
settings	object	No	Location-specific settings
dgDetail	object	No	Dangerous goods details
regionalSetting	object	No	Regional shipping settings
tags	array	No	Tags for categorizing the location

Address Object Fields

Field	Type	Required	Description
contactName	string	No	Contact person's name
emailAddress	string	No	Email address
phoneNumber1	string	No	Primary phone number
phoneNumber2	string	No	Secondary phone number
address1	string	Yes	Street address line 1
address2	string	No	Street address line 2
area	string	No	Area or district
city	string	Yes	City name
stateProvince	string	Yes	State or province
country	string	Yes	Country code (2-letter ISO code)
zipPostalCode	string	Yes	Postal or ZIP code
vatorTaxType	string	No	VAT or tax identifier type

Settings Object Fields

Field	Type	Required	Description
currencyCode	string	No	Default currency code (e.g., USD, EUR)
unitOfWeight	string	No	Default unit of weight (e.g., LB, KG)
unitOfLength	string	No	Default unit of length (e.g., IN, CM)
defaultTimezone	string	No	Default timezone (e.g., America/Chicago)
manualShippingAvailable	boolean	No	Whether manual shipping is available
defaultDescription	array	No	Default product descriptions
defaultDeclaration	string	No	Default customs declaration
logo	object	No	Location logo image
defaultShiptoContactName	string	No	Default ship-to contact name
defaultShiptoEmailAddress	string	No	Default ship-to email address

DG Detail Object Fields

Field	Type	Required	Description
emergPhone	string	No	Emergency phone number for dangerous goods
offererContractHolder	string	No	Dangerous goods contract holder name
contractNo	string	No	Dangerous goods contract number

Regional Setting Object Fields

Field	Type	Required	Description
useItemData	boolean	No	Whether to use item data for shipping
defaultFreightClass	string	No	Default freight class
defaultNmfcCode	string	No	Default NMFC code
autoCalcFreightClass	boolean	No	Whether to auto-calculate freight class
zeroFreightforOutboundThirdParty	boolean	No	Zero freight for outbound third-party shipments
zeroFreightforOutboundCollectOrRecipient	boolean	No	Zero freight for outbound collect/recipient shipments

Error Handling

All APIs follow a consistent error response format:

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

Best Practices

1. Use Reference IDs: Always provide meaningful reference IDs for easier identification
2. Location Groups: Organize locations into logical groups (e.g., by region, type)
3. Default Settings: Configure appropriate default settings to streamline shipping operations
4. Keep Active: Use the active flag to disable locations without deleting them
5. Tags: Use tags for flexible categorization and filtering of locations