API Documentation

Getting Started

Kiloships provides a simple and powerful API for creating and managing shipping labels. Our documentation will help you get up and running quickly.

Base URL

All API requests should be made to:

https://kiloships.com/api

API Endpoints

Create Shipping Label

POSThttps://kiloships.com/api/shipping-labels/domestic

Create a new domestic shipping label

Cancel Shipping Label

DELETEhttps://kiloships.com/api/shipping-labels/domestic/{trackingNumber}

Cancel a domestic shipping label using its tracking number

Track Label

GEThttps://kiloships.com/api/tracking/{trackingNumber}

Get tracking information for a label

City/State Lookup

GEThttps://kiloships.com/api/addresses/city-state?zipCode={zipCode}

Get city and state information for a ZIP code

ZIP Code Lookup

POSThttps://kiloships.com/api/addresses/zipcode

Get ZIP code information for an address

Address Standardization

POSThttps://kiloships.com/api/addresses/address

Get standardized address information

Get Organization Balance

GEThttps://kiloships.com/api/organizations/balance

Get the current balance of your organization

Create Domestic Label

Create a domestic shipping label for USPS services. This endpoint handles label generation, tracking number assignment, and automatic rate calculations.

Endpoint

POST https://kiloships.com/api/shipping-labels/domestic

Authentication

Requires an API key to be included in the request headers:

Authorization: Bearer YOUR_API_KEY

Request Body

Shipment Object

async (optional) - Boolean flag for asynchronous label creation (default: false)

addressTo (required) - Destination address object containing:

name (string) - Recipient's full name
street1 (string) - Primary street address
street2 (string, optional) - Secondary address line
city (string) - City name
state (string) - Two-letter state code
zip (string) - 5-digit or 9-digit ZIP code
country (string) - Two-letter country code (default: "US")
ignoreBadAddress (boolean, optional) - When set to true, bypasses address validation and allows label creation even with unverified addresses. When false or omitted, address validation is enforced (default: false)

addressFrom Object

Sender's address with the same fields as addressTo, including:

name (string) - Sender's full name
street1 (string) - Primary street address
street2 (string, optional) - Secondary address line
city (string) - City name
state (string) - Two-letter state code
zip (string) - 5-digit or 9-digit ZIP code
country (string) - Two-letter country code (default: "US")
ignoreBadAddress (boolean, optional) - When set to true, bypasses address validation and allows label creation even with unverified addresses. When false or omitted, address validation is enforced (default: false)

Parcels Array

Array containing a single parcel object with:

weight (string) - Package weight
massUnit (string) - Weight unit ("oz" or "lb")
length (string) - Package length
width (string) - Package width
height (string) - Package height
distanceUnit (string) - Dimension unit ("in" or "cm")

Service Level

servicelevelToken (required) - One of:

usps_ground_advantage - USPS Ground Advantage
usps_priority - USPS Priority Mail
usps_priority_express - USPS Priority Mail Express
usps_media_mail - USPS Media Mail

Metadata

metadata (optional) - Array of strings for custom messages or references

Customs Form

The customsForm object is optional and is used for international shipments that require customs documentation.

Fields

contentComments - Optional comments about the shipment contents
customsContentType - Type of contents being shipped:
- MERCHANDISE
- SAMPLE
- GIFT
- DOCUMENTS
- RETURNED_GOODS
- OTHER
contents - Array of items in the shipment, each containing:
- itemDescription - Description of the item
- itemQuantity - Number of items
- itemTotalValue - Total value of the items
- weightUOM - Unit of measure for weight (oz or lb)
- itemTotalWeight - Total weight of the items
- HSTariffNumber - Optional Harmonized System tariff number
- countryofOrigin - Country where the item was manufactured
- itemCategory - Optional category of the item
- itemSubcategory - Optional subcategory of the item

Special Requirements for Military and Diplomatic Addresses

Additional information is required when shipping to or from:

MPOs (Military Post Offices)
APOs (Army Post Offices)
FPOs (Fleet Post Offices)
DPOs (Diplomatic Post Offices)
U.S. Possessions, Territories, and Freely Associated States (PTFAS)

For these addresses, you must include:

Complete unit information in the address
Valid military or diplomatic ZIP code
Proper military or diplomatic state code (AA, AE, AP)
Detailed item descriptions in the customs form
Accurate country of origin for all items

Example Customs Form

customs-form-example.json

{
  "contentComments": "Sample shipment for testing",
  "customsContentType": "MERCHANDISE",
  "contents": [
    {
      "itemDescription": "Cotton T-Shirt",
      "itemQuantity": 2,
      "itemTotalValue": 29.99,
      "weightUOM": "oz",
      "itemTotalWeight": 8,
      "HSTariffNumber": "6109.10.0000",
      "countryofOrigin": "US",
      "itemCategory": "Clothing",
      "itemSubcategory": "T-Shirts"
    }
  ]
}

Example Request

curl -X POST https://kiloships.com/api/shipping-labels/domestic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment": {
      "async": false,
      "parcels": [{
        "width": "0.25",
        "height": "6",
        "length": "9",
        "weight": "0.5",
        "massUnit": "lb",
        "distanceUnit": "in"
      }],
      "addressTo": {
        "zip": "63118",
        "city": "St. Louis",
        "name": "asd Doe",
        "state": "MO",
        "country": "US",
        "street1": "1100 Wyoming",
        "street2": "Suite 150"
      },
      "addressFrom": {
        "zip": "63116",
        "city": "St. Louis",
        "name": "John Smith",
        "state": "MO",
        "country": "US",
        "street1": "4120 Bingham"
      }
    },
    "servicelevelToken": "usps_ground_advantage",
    "metadata": [
      "Message 1",
      "Message 2",
      "Message 3"
    ]
  }'

Response Fields

rate - Object containing pricing and service details
parcel - Object containing package details
status - Current label status
labelUrl - URL to download the shipping label PDF
trackingNumber - Carrier tracking number

Example Response

create-label-response.json

{
  "rate": {
    "amount": "3.74",
    "currency": "USD",
    "objectId": "DUXP0XXXU101080",
    "provider": "usps",
    "amountLocal": 3.74,
    "currencyLocal": "USD",
    "carrierAccount": "",
    "servicelevelName": "usps_ground_advantage",
    "servicelevelToken": "usps_ground_advantage"
  },
  "parcel": {
    "weight": 0.5,
    "weightUOM": "LB"
  },
  "status": "CREATED",
  "labelUrl": "https://photo.kiloships.com/shipping-labels/domestic/label-1-1743838485434-9200190384072900005162.pdf",
  "messages": [],
  "metadata": [
    "Message 1",
    "Message 2",
    "Message 3"
  ],
  "objectId": "DUXP0XXXU101080",
  "objectOwner": "",
  "objectState": "CREATED",
  "objectCreated": "2025-04-05T07:34:46.109Z",
  "objectUpdated": "2025-04-05T07:34:46.109Z",
  "trackingNumber": "9200190384072900005162",
  "trackingStatus": "CREATED",
  "trackingUrlProvider": "USPS",
  "labelImageUrl": "https://photo.kiloships.com/shipping-labels/domestic/label-1-1743838485434-9200190384072900005162.pdf",
  "chargeAmount": 3.74
}

Cancel Domestic Label

Endpoint

DELETEhttps://kiloships.com/api/shipping-labels/domestic/{trackingNumber}

Cancel a domestic shipping label using its tracking number. This endpoint supports both session-based authentication and API key authentication.

Path Parameters

Parameter	Type	Required	Description
trackingNumber	string	Yes	The tracking number of the label to cancel

Authentication

This endpoint supports two authentication methods:

Session Authentication: Use when making requests from a web browser with an active session
API Key Authentication: Use when making programmatic requests with an API key

Only one authentication method is required. The endpoint will first check for session authentication, and if that fails, it will check for API key authentication.

Example Request

curl

curl -X DELETE \
  "https://kiloships.com/api/shipping-labels/domestic/9405511298370938473298" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

response.json

{
  "success": true,
  "data": {
    "id": 123,
    "trackingNumber": "9405511298370938473298",
    "status": "CANCELLED",
    "cancelledAt": "2024-04-21T12:00:00Z"
  },
  "message": "Shipping label successfully canceled"
}

The status field indicates the current state of the label:

CANCELLED - The label has been successfully canceled
DISPUTED - A refund request has been initiated for the label

SCAN Form API

The SCAN Form API allows you to create USPS SCAN (Shipment Confirmation Acceptance Notice) forms for multiple tracking numbers. This form serves as proof of shipment for multiple packages in a single document.

Create SCAN Form

POSThttps://kiloships.com/api/scan-form

Create a USPS SCAN form for multiple tracking numbers

Authentication

Requires an API key to be included in the request headers:

Authorization: Bearer YOUR_API_KEY

Request Body

Required Fields:

mailingDate - Format: YYYY-MM-DD
entryFacilityZIPCode - 5-digit or 9-digit ZIP code
destinationEntryFacilityType - One of:
- "NONE"
- "DESTINATION_NETWORK_DISTRIBUTION_CENTER"
- "DESTINATION_SECTIONAL_CENTER_FACILITY"
- "DESTINATION_DELIVERY_UNIT"
- "DESTINATION_SERVICE_HUB"
fromAddress - Sender's address object
shipment.trackingNumbers - Array of tracking numbers

fromAddress Object:

streetAddress - Primary street address (required)
city - City name (required)
state - Two-letter state code (required)
ZIPCode - 5-digit or 9-digit ZIP code (required)
firstName - Recipient's first name (optional)
lastName - Recipient's last name (optional)
firm - Company name (optional)
secondaryAddress - Suite, Apt, etc. (optional)
ZIPPlus4 - ZIP+4 code (optional)
urbanization - Urbanization code for Puerto Rico (optional)
ignoreBadAddress - Bypass address validation (optional)

Optional Fields:

overwriteMailingDate - Boolean to overwrite mailing date

Example Request

scan-form-request.json

{
  "mailingDate": "2024-02-20",
  "entryFacilityZIPCode": "12345",
  "destinationEntryFacilityType": "NONE",
  "fromAddress": {
    "streetAddress": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "ZIPCode": "12345"
  },
  "shipment": {
    "trackingNumbers": [
      "9400100000000000000000",
      "9400100000000000000001"
    ]
  }
}

Response Fields

form - Form type identifier
imageType - Type of image (PDF, TIFF, etc.)
labelType - Type of label
mailingDate - Confirmed mailing date
scanFormImage - URL to download the form
manifestNumber - Optional manifest number
shipment - Object containing confirmed tracking numbers
fromAddress - Confirmed sender address

Example Success Response

scan-form-response.json

{
  "form": "5630",
  "imageType": "PDF",
  "labelType": "8.5x11LABEL",
  "mailingDate": "2024-02-20",
  "overwriteMailingDate": false,
  "entryFacilityZIPCode": "12345",
  "destinationEntryFacilityType": "NONE",
  "shipment": {
    "trackingNumbers": [
      "9400100000000000000000",
      "9400100000000000000001"
    ]
  },
  "manifestNumber": "123456789",
  "fromAddress": {
    "streetAddress": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "ZIPCode": "12345"
  },
  "scanFormImage": "https://your-cloudflare-url.com/scan-forms/form.pdf"
}

Important Notes

All tracking numbers must belong to your organization
The SCAN form will be generated as a PDF and stored in Cloudflare R2
The mailing date must be in YYYY-MM-DD format
ZIP codes must be either 5 digits or 9 digits (with hyphen)
All required fields are validated before making the request to USPS

Tracking Labels

Track your packages using our tracking API. Each tracking request requires authentication and has a small fee associated with it.

Track by Tracking Number

GEThttps://kiloships.com/api/tracking/{trackingNumber}

Get tracking information for a package

Query Parameters

Parameter	Type	Required	Description
`responseType`	string	No	Type of tracking response (SUMMARY or DETAIL)

Authentication

This endpoint requires either:

API Key in the Authorization header
Valid user session with organization access

Example Request

tracking-request.sh

curl -X GET 'https://kiloships.com/api/tracking/9405511298370938472938?responseType=SUMMARY' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

tracking-response.json

{
  "data": {
    "trackingNumber": "9405511298370938472938",
    "status": "In Transit",
    "statusCategory": "IN_TRANSIT",
    "statusSummary": "Your package is moving within the USPS network",
    "mailClass": "First-Class Package Service",
    "mailType": "Package",
    "originCity": "New York",
    "originState": "NY",
    "originZIP": "10001",
    "destinationCity": "Los Angeles",
    "destinationState": "CA",
    "destinationZIP": "90001",
    "trackingEvents": [
      {
        "eventType": "In Transit",
        "eventTimestamp": "2024-04-17T10:30:00Z",
        "eventCity": "New York",
        "eventState": "NY",
        "eventZIP": "10001",
        "eventCode": "IT"
      }
    ]
  },
  "chargeAmount": 0.01
}

Address APIs

The Address APIs provide utilities for validating and standardizing address information, including city/state lookup, ZIP code lookup, and address standardization. These endpoints help ensure accurate shipping addresses and improve delivery success rates.

City/State Lookup

Get city and state information for a given ZIP code.

Endpoint

GET https://kiloships.com/api/addresses/city-state?zipCode={zipCode}

Parameters

zipCode (required) - 5-digit ZIP code

Response

city - City name
state - Two-letter state code
ZIPCode - 5-digit ZIP code

Example Request

city-state-lookup.sh

curl -X GET "https://kiloships.com/api/addresses/city-state?zipCode=10001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

city-state-response.json

{
  "city": "New York",
  "state": "NY",
  "ZIPCode": "10001"
}

ZIP Code Lookup

Get ZIP code information for a given address.

Endpoint

POST https://kiloships.com/api/addresses/zipcode

Request Body

streetAddress (required) - Primary street address
city (required) - City name
state (required) - Two-letter state code AA AE AL AK AP AS AZ AR CA CO CT DE DC FM FL GA GU HI ID IL IN IA KS KY LA ME MH MD MA MI MN MS MO MP MT NE NV NH NJ NM NY NC ND OH OK OR PW PA PR RI SC SD TN TX UT VT VI VA WA WV WI WY
secondaryAddress (optional) - Apartment, suite, etc.
firm (optional) - Company or organization name
urbanization (optional) - Urbanization code (Puerto Rico only)

Response

address - Object containing:
- streetAddress - Standardized street address
- city - City name
- state - Two-letter state code
- ZIPCode - 5-digit ZIP code
- ZIPPlus4 - ZIP+4 code (if available)
- secondaryAddress - Standardized secondary address

Example Request

zipcode-lookup-request.json

curl -X POST "https://kiloships.com/api/addresses/zipcode" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "streetAddress": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "secondaryAddress": "Suite 3000"
  }'

Example Response

zipcode-lookup-response.json

{
  "address": {
    "streetAddress": "350 5TH AVE",
    "secondaryAddress": "STE 3000",
    "city": "NEW YORK",
    "state": "NY",
    "ZIPCode": "10118",
    "ZIPPlus4": "0110"
  }
}

Address Standardization

Get standardized address information and validate address components.

Endpoint

POST https://kiloships.com/api/addresses/address

Request Body

streetAddress (required) - Primary street address
city (required*) - City name (*either city or ZIP code required)
state (required) - Two-letter state code AA AE AL AK AP AS AZ AR CA CO CT DE DC FM FL GA GU HI ID IL IN IA KS KY LA ME MH MD MA MI MN MS MO MP MT NE NV NH NJ NM NY NC ND OH OK OR PW PA PR RI SC SD TN TX UT VT VI VA WA WV WI WY
secondaryAddress (optional) - Apartment, suite, etc.
firm (optional) - Company or organization name
urbanization (optional) - Urbanization code (Puerto Rico only)
ZIPCode (optional*) - 5-digit ZIP code (*either city or ZIP code required)

Response

firm - Standardized company name (if provided)
address - Object containing:
- streetAddress - Standardized street address
- streetAddressAbbreviation - Abbreviated street address
- secondaryAddress - Standardized secondary address
- city - Standardized city name
- cityAbbreviation - Abbreviated city name
- state - Two-letter state code
- ZIPCode - 5-digit ZIP code
- ZIPPlus4 - ZIP+4 code
additionalInfo - Object containing:
- deliveryPoint - Delivery point code
- carrierRoute - Carrier route code
- DPVConfirmation - Delivery point validation status
- DPVCMRA - Commercial mail receiving agency status
- business - Business address indicator
- centralDeliveryPoint - Central delivery point indicator
- vacant - Vacant address indicator
corrections - Array of correction codes and descriptions
matches - Array of match codes and descriptions
warnings - Array of warning messages

Example Request

address-standardization-request.json

curl -X POST "https://kiloships.com/api/addresses/address" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "streetAddress": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "secondaryAddress": "Suite 3000"
  }'

Example Response

address-standardization-response.json

{
  "address": {
    "streetAddress": "350 5TH AVE",
    "streetAddressAbbreviation": "350 5TH AVE",
    "secondaryAddress": "STE 3000",
    "city": "NEW YORK",
    "cityAbbreviation": "NEW YORK",
    "state": "NY",
    "ZIPCode": "10118",
    "ZIPPlus4": "0110"
  },
  "additionalInfo": {
    "deliveryPoint": "00",
    "carrierRoute": "C006",
    "DPVConfirmation": "Y",
    "DPVCMRA": "N",
    "business": "Y",
    "centralDeliveryPoint": "N",
    "vacant": "N"
  },
  "matches": [
    {
      "code": "A",
      "text": "Exact match"
    }
  ]
}

Get Zone

GET

https://kiloships.com/api/addresses/zone/number?originZIPCode={originZIPCode}&destinationZIPCode={destinationZIPCode}&mailingDate={mailingDate}

Get the shipping zone between two ZIP codes for a specific mailing date

Query Parameters

originZIPCode(required) - Origin ZIP code

destinationZIPCode(required) - Destination ZIP code

mailingDate(required) - Mailing date in YYYY-MM-DD format

Response

get-zone-response.json

{
  "zone": 5
}

Example Request

get-zone-request.sh

curl -X GET "https://kiloships.com/api/addresses/zone?originZIPCode=90210&destinationZIPCode=10001&mailingDate=2024-04-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Organization Balance

Get the current balance of your organization. This endpoint requires authentication and returns the available balance that can be used for shipping labels and other services.

Endpoint

GET https://kiloships.com/api/organizations/balance

Authentication

Requires an API key to be included in the request headers:

Authorization: Bearer YOUR_API_KEY

Example Request

get-balance-request.sh

curl -X GET "https://kiloships.com/api/organizations/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

get-balance-response.json

{
    "currentBalance": 728.8
}

Response Fields

currentBalance - Current available balance in USD

Error Handling

Error Response Format

When an error occurs, the API will return a JSON response with the following structure:

success - Boolean indicating if the request was successful
message - A general error message
code - HTTP status code
error - Detailed error object:
- code - Error code
- message - Error message
- errors - Array of specific error details:
  - title - Error type
  - detail - Detailed error message
  - source - Object indicating the error source

Common Error Codes

400 - Bad Request - Invalid input parameters or validation errors
401 - Unauthorized - Invalid or missing API key
402 - Payment Required - Insufficient balance
404 - Not Found - Resource not found
429 - Too Many Requests - Rate limit exceeded
500 - Internal Server Error - Server-side error

Example Error Response

error-response.json

{
  "success": false,
  "message": "Bad Request",
  "code": "400",
  "error": {
    "code": "400",
    "message": "Bad Request",
    "errors": [
      {
        "title": "Bad Request",
        "detail": "five digits are required",
        "source": {
          "parameter": "toAddress.ZIPCode"
        }
      }
    ]
  }
}

Common Validation Errors

toAddress.ZIPCode - ZIP code must be exactly 5 digits
fromAddress.ZIPCode - ZIP code must be exactly 5 digits
servicelevelToken - Must be a valid service level
weight - Must be a positive number
dimensions - Length, width, and height must be positive numbers