Skip to content
Guides
/Addresses/
Validate Addresses
Last updated

Validate Addresses

ShipStation provides two methods for validating addresses:

  1. Direct validation using the dedicated address validation endpoint (ShipStation API customers only)
  2. Indirect validation using the validate_address property when creating shipments, labels, or getting rates

Direct Address Validation (ShipStation API Customers Only)

ShipStation API Customers Only

The direct address validation endpoint (POST /v2/addresses/validate) is only available to ShipStation API customers (formerly ShipEngine).

ShipStation platform customers should use the indirect validation method with the validate_address property.

If you're a ShipStation API customer (formerly ShipEngine), you can validate addresses directly using the dedicated validation endpoint before creating shipments or labels.

POST /v2/addresses/validate

curl -i -X POST \
  https://api.shipstation.com/v2/addresses/validate \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '[
    {
      "name": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US"
    }
  ]'

This endpoint allows you to:

  • Validate addresses independently of shipment/label creation
  • Batch validate multiple addresses
  • Get detailed validation results including address corrections and confidence scores
  • Validate addresses before committing to a shipment workflow

For complete details on using this endpoint, see the API Reference.

Indirect Address Validation

All ShipStation V2 API customers can validate the ship_to address inline when creating shipments, labels, or getting rates by adding the validate_address property to the request body.

Validation Options

Set the validate_address property to one of the following values:

ValueDescription
no_validation(Default) No address validation is performed
validate_onlyValidates the address and returns an error if invalid, but does not modify the address
validate_and_cleanValidates the address, corrects it if possible (e.g., adds +4 ZIP code), and returns an error if invalid

Where You Can Use Indirect Validation

You can use the validate_address property with the following endpoints:

  • POST /v2/labels - Validate when creating labels
  • POST /v2/shipments - Validate when creating shipments
  • POST /v2/rates - Validate when getting rates

Validating When Creating Labels

Add the validate_address property to the label request body to validate the ship_to address when purchasing a label.

Requirements

  • Add the validate_address property to the purchase label request body (POST /v2/labels)
  • Set the property value to validate_only or validate_and_clean

Sample Request

In this example, we add the validate_address property to the label request body with the validate_and_clean value.

POST /v2/labels

curl -i -X POST \
  https://api.shipstation.com/v2/labels \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ship_to_service_point_id": "614940",
    "ship_from_service_point_id": "614940",
    "shipment": {
      "carrier_id": "se-1234567",
      "service_code": "usps_first_class_mail",
      "requested_shipment_service": "usps_priority_mail",
      "external_order_id": "1232434",
      "hold_until_date": "2025-01-15T00:00:00.000Z",
      "ship_by_date": "2025-01-15T00:00:00.000Z",
      "deliver_by_date": "2025-01-20T00:00:00.000Z",
      "retail_rate": {
        "currency": "usd",
        "amount": 12
      },
      "store_id": "se-12345",
      "items": [],
      "notes_from_buyer": "Please handle with care",
      "notes_to_buyer": "Thank you for your order!",
      "notes_for_gift": "Happy Birthday!",
      "internal_notes": "Check packaging before shipping",
      "is_gift": true,
      "assigned_user": "user@example.com",
      "amount_paid": {
        "currency": "usd",
        "amount": 12
      },
      "shipping_paid": {
        "currency": "usd",
        "amount": 12
      },
      "tax_paid": {
        "currency": "usd",
        "amount": 12
      },
      "zone": 1,
      "display_scheme": "label",
      "tax_identifiers": [
        {
          "taxable_entity_type": "shipper",
          "identifier_type": "vat",
          "issuing_authority": "US",
          "value": "value"
        }
      ],
      "external_shipment_id": "1234556",
      "shipment_number": "10001",
      "ship_date": "2018-09-23T00:00:00Z",
      "ship_to": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instruction",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "ship_from": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instructions",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "warehouse_id": null,
      "return_to": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instructions",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "is_return": true,
      "confirmation": "none",
      "customs": {
        "terms_of_trade_code": "ddp",
        "contents": "gift",
        "non_delivery": "return_to_sender"
      },
      "advanced_options": {
        "bill_to_account": "123456789",
        "bill_to_country_code": "US",
        "bill_to_party": "third_party",
        "bill_to_postal_code": "28005",
        "contains_alcohol": true,
        "delivered_duty_paid": true,
        "dry_ice": true,
        "dry_ice_weight": {
          "value": 23,
          "unit": "pound"
        },
        "non_machinable": true,
        "saturday_delivery": true,
        "fedex_freight": {
          "shipper_load_and_count": "shipper_load_and_count",
          "booking_confirmation": "today"
        },
        "use_ups_ground_freight_pricing": true,
        "freight_class": "77.5",
        "custom_field1": "custom field 1",
        "custom_field2": "custom field 2",
        "custom_field3": "custom field 3",
        "origin_type": null,
        "additional_handling": true,
        "shipper_release": true,
        "collect_on_delivery": {
          "payment_type": "any",
          "payment_amount": {
            "currency": "USD",
            "amount": 12
          }
        },
        "third_party_consignee": true,
        "dangerous_goods": true,
        "dangerous_goods_contact": {
          "name": "Michael Robinson",
          "phone": "123456578789"
        },
        "movement_indicator": "b2b",
        "windsor_framework_details": {
          "movement_indicator": "b2b",
          "not_at_risk": true
        },
        "ancillary_endorsements_option": "forward",
        "return_pickup_attempts": 3,
        "own_document_upload": false,
        "limited_quantity": false,
        "event_notification": false,
        "fragile": false,
        "delivery_as_addressed": false,
        "return_after_first_attempt": false,
        "regulated_content_type": null,
        "netstamps_options": {
          "row": 1,
          "column": 1
        },
        "suppress_carrier_generated_documents": [
          "commercial_invoice"
        ],
        "transparency_codes": [
          {
            "order_item_id": "12345678901234",
            "codes": [
              "AZ:XXXXXXXXXXXX"
            ]
          }
        ]
      },
      "insurance_provider": "none",
      "tags": [],
      "order_source_code": "amazon_ca",
      "packages": [
        {
          "package_id": "se-123456",
          "package_code": "thick_envelope",
          "package_name": "Flat Rate Envelope",
          "weight": {
            "value": 23,
            "unit": "pound"
          },
          "dimensions": {
            "unit": "inch",
            "length": 2,
            "width": 2,
            "height": 1
          },
          "insured_value": [
            {
              "currency": "usd",
              "amount": 0
            }
          ],
          "label_messages": {
            "reference1": "Reference",
            "reference2": "Reference 2",
            "reference3": "Reference 3"
          },
          "external_package_id": "se-1234545",
          "content_description": "Hand knitted wool socks",
          "products": []
        }
      ],
      "comparison_rate_type": "retail"
    },
    "is_return_label": true,
    "rma_number": "asd12323",
    "charge_event": "carrier_default",
    "outbound_label_id": "se-28529731",
    "test_label": true,
    "validate_address": "no_validation",
    "label_download_type": "url",
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
  }'

Response: Address Successfully Validated

If the address is fully validated and no changes are required, the response will be your standard response when creating a label. There are no additional properties to indicate the address validation status.

Response: Address Cleaned

If the validation finds a more precise address match in the available database, the shipment will simply include the updated ship_to address values. In this example, the validation added the +4 code to the postal_code property in the ship_to object.

{
 "ship_to":
    {
     "name": "John Doe",
     "phone": "+1 204-253-9411 ext. 123",
     "email": "example@example.com",
     "company_name": "My Company",
     "address_line1": "4301 Bull Creek Rd",
     "address_line2": "Suite 300",
     "city": "Austin",
     "state": "TX",
     "postal_code": "78731-5933",
     "country_code": "US",
     "address_residential_indicator": "no"
    }
}

Response: Address Validation Error

If the address cannot be validated, we'll return an error and the label will not be created. The error will provide the details you need to locate the source of the validation issue so you can modify the address and attempt to create the label again.

{
    "request_id": "f0cab3d6-384e-4cce-9ba6-36f4e0de08f0",
    "errors": [
        {
            "error_source": "shipstation",
            "error_type": "business_rules",
            "error_code": "invalid_address",
            "message": "Invalid City, State, or Zip",
            "field_name": "ship_to",
            "detail_code": "unsupported_country"
        }
    ]
}

The level of detail provided in the message and detail_code properties will vary depending on the country the address is located in and the validation level available.

Validating When Creating Shipments

Add the validate_address property to the shipment request body to validate the ship_to address when creating a shipment.

Requirements

  • Add the validate_address property to the create shipment request body (POST /v2/shipments)
  • Set the property value to validate_only or validate_and_clean

Sample Request

In this example, we add the validate_address property to the shipment request body with the validate_and_clean value.

POST /v2/shipments

curl -i -X POST \
  https://api.shipstation.com/v2/shipments \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "shipments": [
      {
        "validate_address": "no_validation",
        "external_shipment_id": "1751939189",
        "carrier_id": "se-2774150",
        "create_sales_order": true,
        "store_id": "1582173",
        "notes_from_buyer": "I am a note from the buyer",
        "notes_to_buyer": "Thank you for your order!",
        "notes_for_gift": "I am a gift note",
        "internal_notes": "Check packaging before shipping",
        "is_gift": true,
        "zone": 0,
        "display_scheme": "paperless",
        "requested_shipment_service": "usps_priority_mail",
        "deliver_by_date": "2025-01-20T00:00:00.000Z",
        "assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
        "shipment_status": "pending",
        "amount_paid": {
          "currency": "usd",
          "amount": 12
        },
        "shipping_paid": {
          "currency": "usd",
          "amount": 12
        },
        "tax_paid": {
          "currency": "usd",
          "amount": 12
        },
        "ship_to": {
          "name": "John Doe",
          "phone": "+1 204-253-9411 ext. 123",
          "email": "example@example.com",
          "company_name": "The Home Depot",
          "address_line1": "1999 Bishop Grandin Blvd.",
          "address_line2": "Unit 408",
          "address_line3": "Building #7",
          "city_locality": "Winnipeg",
          "state_province": "Manitoba",
          "postal_code": "78756-3717",
          "country_code": "CA",
          "address_residential_indicator": "yes",
          "instructions": "any instruction",
          "geolocation": [
            {
              "type": "what3words",
              "value": "cats.with.thumbs"
            }
          ]
        },
        "ship_from": {
          "name": "John Doe",
          "phone": "+1 204-253-9411 ext. 123",
          "email": "example@example.com",
          "company_name": "The Home Depot",
          "address_line1": "1999 Bishop Grandin Blvd.",
          "address_line2": "Unit 408",
          "address_line3": "Building #7",
          "city_locality": "Winnipeg",
          "state_province": "Manitoba",
          "postal_code": "78756-3717",
          "country_code": "CA",
          "address_residential_indicator": "yes",
          "instructions": "any instructions",
          "geolocation": [
            {
              "type": "what3words",
              "value": "cats.with.thumbs"
            }
          ]
        },
        "warehouse_id": "se-2774150",
        "items": [],
        "packages": [
          {
            "package_id": "se-123456",
            "package_code": "thick_envelope",
            "package_name": "Flat Rate Envelope",
            "weight": {
              "value": 23,
              "unit": "pound"
            },
            "dimensions": {
              "unit": "inch",
              "length": 2,
              "width": 2,
              "height": 1
            },
            "insured_value": [
              {
                "currency": "usd",
                "amount": 0
              }
            ],
            "label_messages": {
              "reference1": "Reference",
              "reference2": "Reference 2",
              "reference3": "Reference 3"
            },
            "external_package_id": "se-1234545",
            "content_description": "Hand knitted wool socks",
            "products": []
          }
        ]
      }
    ]
  }'

Response Behavior

The response behavior for shipment creation is the same as for label creation:

  • Successfully validated: Standard shipment creation response with no additional validation properties
  • Address cleaned: The ship_to object in the response will include the corrected address values
  • Validation error: Returns an error response with details about the validation failure, and the shipment is not created

Validating When Getting Rates

Add the validate_address property to the rates request body to validate the ship_to address when comparing rates.

Requirements

  • Add the validate_address property to the rates request body (POST /v2/rates)
  • Set the property value to validate_only or validate_and_clean

Sample Request

In this example, we add the validate_address property to the rates request body with the validate_and_clean value.

POST /v2/rates

curl -i -X POST \
  https://api.shipstation.com/v2/rates/estimate \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "carrier_id": "se-1234567",
    "from_country_code": "CA",
    "from_postal_code": "78756-3717",
    "from_city_locality": "Austin",
    "from_state_province": "Austin",
    "to_country_code": "CA",
    "to_postal_code": "78756-3717",
    "to_city_locality": "Austin",
    "to_state_province": "Houston",
    "weight": {
      "value": 3,
      "unit": "pound"
    },
    "dimensions": {
      "unit": "inch",
      "length": 2,
      "width": 2,
      "height": 1
    },
    "confirmation": "none",
    "address_residential_indicator": "unknown",
    "ship_date": "2018-09-23T15:00:00.000Z"
  }'

Response Behavior

The response behavior for rate requests is the same as for label and shipment creation:

  • Successfully validated: Standard rates response with no additional validation properties
  • Address cleaned: The ship_to object in the response will include the corrected address values
  • Validation error: Returns an error response with details about the validation failure, and no rates are returned

Legacy API Migration

Rate Shopping

Shipstation
  • Facebook
  • Linkedin
  • Instagram
Auctane
ShipStation is powered by Auctane, a global delivery experience company. © 2026 Auctane, Inc. All rights reserved