---
title: "Create an Insurance Policy"
method: POST
path: "/2024-09/insurances/policies"
tags: ["Insurance"]
---

# Create an Insurance Policy

`POST /2024-09/insurances/policies`

## Request

- Base URL: `https://public-api.easyship.com`
- URL: `https://public-api.easyship.com/2024-09/insurances/policies`
- Auth: HTTP bearer

Create insurance for a shipment whose label isn't provided by Easyship.
For the shipment whose label is provided by Easyship, please use [Shipment Insurance Endpoint](https://developers.easyship.com/reference/shipments_insure_create) to insure it.

Easyship relies on the tracking number and courier service ID to validate the shipment. Once the tracking record is successfully established, the insurance will be automatically set up and charged.

If the tracking record is initiated using the tracking endpoint `POST /:version/trackings`, it becomes valid for insurance only after receiving a response from the courier service, and within 24 hours of that time.

Required authorization scope: `public.insurance_policy_3p:write`

> This API requires an updated contract with Easyship. Get in touch with your account manager or Easyship Support Team.

## Request body

- ExternalShipmentInsuranceCreate: Tracking Create params
  - `tracking_number` string, required
  - `courier_service_id` string, uuid: unique identifier for a courier service
  - `courier_service_name` string: Name of the courier service. Required if `courier_service_id` is not provided. For courier services that Easyship doesn't support label generation, please retrieve the name using `GET /trackings/external_courier_services`
  - `platform_order_number` PlatformOrderNumber (unresolved $ref)
  - `origin_address_id` string, uuid: ID of origin address. Required if the `origin_address` object is not provided. If provided, the origin address attributes will be ignored.
  - `origin_address` Address
    - `line_1` string: First line of the street address
    - `line_2` string, nullable: Second line of the street address
    - `line_3` string, nullable: Third line of the street address. This value is saved and returned by the API, but not every courier includes it on the label, so it may be ignored if the selected courier does not support a third address line.
    - `state` string: State, Province, or other top-level administrative region. Mandatory for these countries: AU, CA, CN, ID, MX, MY, TH, US, VN. Use abbreviations for naming the state if possible (2 letters for the US/CA, 2 or 3 letters for AU). For countries using provinces, use the full province names.
    - `city` string: City or Suburb
    - `postal_code` string, nullable: Postal code. Leave it null or 0 if the country does not have postal codes. Mandatory for these countries: AD, AF, AI, AL, AM, AQ, AR, AS, AT, AU, AX, AZ, BA, BB, BD, BE, BG, BL, BM, BN, BQ, BR, BT, BV, BY, CA, CC, CH, CL, CN, CO, CR, CU, CV, CX, CY, CZ, DE, DK, DO, DZ, EC, EE, EG, EH, ES, ET, FI, FK, FM, FO, FR, GA, GB, GE, GF, GG, GI, GL, GP, GR, GS, GT, GU, GW, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JO, JP, KG, KH, KR, KW, KY, KZ, LA, LB, LI, LK, LR, LS, LT, LU, LV, MA, MC, MD, ME, MF, MG, MH, MK, MM, MN, MP, MQ, MT, MV, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NZ, OM, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, RE, RO, RS, RU, SD, SE, SG, SH, SI, SJ, SK, SM, SN, SS, SV, SX, SZ, TC, TD, TH, TJ, TM, TN, TR, TW, UA, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, WF, WS, YT, ZA, ZM.
    - `country_alpha2` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW': Country Code in Alpha-2 format (ISO 3166-1)
    - `company_name` string, nullable: The company or organization at the address
    - `contact_name` string: The full name of a person at the address
    - `contact_phone` string, nullable: Phone number used to reach the person in contact_name (may or may not be SMS-ready)
    - `contact_email` string, email: Email address used to reach the person in `contact_name"
  - `destination_address` object
    - `line_1` string, required: First line of the street address
    - `line_2` string, nullable: Second line of the street address
    - `line_3` string, nullable: Third line of the street address. Saved and returned on shipments only (ignored by rates and trackings). Not every courier includes it on the label, so it may be ignored if the selected courier does not support a third address line.
    - `state` string, nullable, required: State, Province, or other top-level administrative region. Mandatory for these countries: AU, CA, CN, ID, MX, MY, TH, US, VN. Use abbreviations for naming the state if possible (2 letters for the US/CA, 2 or 3 letters for AU). For countries using provinces, use the full province names.
    - `city` string, required: City or Suburb
    - `postal_code` string, required: Postal code. Mandatory for most countries (if not applicable, for example Hong Kong, leave null or 0)
    - `country_alpha2` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW': Country Code in Alpha-2 format (ISO 3166-1)
    - `company_name` string, nullable: The company or organization at the address
    - `contact_name` string, required: The full name of a person at the address
    - `contact_phone` string, required: Phone number used to reach the person in contact_name (may or may not be SMS-ready)
    - `contact_email` string, email, required: Email address used to reach the person in `contact_name`
    - `delivery_instructions` string, nullable: Delivery instructions for the address, see [Delivery Instructions](https://developers.easyship.com/page/delivery-instructions).
  - `items` object[]
    - `description` string, required
    - `quantity` number: Quantity of the item. It will be set to 1 if not provided.
  - `insurance` object, required
    - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SKK' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'BTC' | 'JEP' | 'EEK' | 'GHC' | 'MTL' | 'TMM' | 'YEN' | 'ZWD' | 'ZWL' | 'ZWN' | 'ZWR', required: ISO-4217 three-letter alphabetic currency code (e.g. USD, EUR, GBP)
    - `insured_value` number, float, required: The value of the shipment that is being insured. Limitation is 10000 USD.

## Response `201`

Insurance policy successfully created

- InsuranceSingle: Insurance details
  - `insurance_policy` Insurance
    - `policy_type` 'easyship_label' | 'external_label': Whether this policy is for an Easyship-generated label or an externally generated one.
    - `easyship_insurance_id` string: Easyship insurance ID
    - `insurance_fee` number: Insurance fee
    - `total_insured_value` number: Amount to insure with Easyship's insurance provider.
    - `currency` InsuredCurrency (unresolved $ref)
    - `tracking_number` string, nullable
    - `recipient` 'buyer' | 'merchant': Recipient type
    - `state` 'pending_request' | 'confirmed' | 'failed' | 'pending_void' | 'voided' | 'awaiting' | 'active' | 'canceled' | 'expired': State of the policy. `easyship_label` policies use Policy's state machine; `external_label` policies use InsurancePolicy's (see `policy_type`) -- the two don't share a vocabulary.
    - `claim_state` 'not_filed' | 'filed_by_client' | 'filed_to_courier_damaged' | 'filed_to_courier_lost' | 'rejected_damaged' | 'rejected_lost' | 'accepted_damaged' | 'accepted_lost' | 'voided' | 'not_started' | 'in_progress' | 'filed' | 'accepted' | 'refund_initiated' | 'refund_completed' | 'refund_failed' | 'rejected' | 'closed': Claim state of the insurance. `easyship_label` policies use Policy's claim state machine; `external_label` policies use InsurancePolicy's (see `policy_type`) -- the two don't share a vocabulary.
    - `easyship_shipment_id` string, nullable: Readable identifier prefixed with ES (Easyship) and destination country code. Null for `external_label` policies, which have no associated Easyship shipment.
    - `tracking_id` string, uuid, nullable: Tracking ID. Null for `external_label` policies, which have no associated Easyship shipment.
    - `source` 'cloud' | 'efulfilment' | 'external', nullable: Source of the insured shipment. Null for `external_label` policies, which have no associated Easyship shipment.
    - `courier_name` string, nullable: Name of the courier handling the insured shipment. Null if no courier has been assigned yet.
    - `platform_order_id` string, nullable: Platform (e.g. Shopify) order ID associated with the insured shipment. Null if not captured for this policy.
    - `insurance_valid_from` string, date-time, nullable: Start of the insurance coverage window. Null for `easyship_label` policies, which have no separate validity window of their own -- they're bound to the shipment's own lifecycle. May also be null for older `external_label` policies that predate this tracking.
    - `insurance_valid_until` string, date-time, nullable: End of the insurance coverage window. Null for `easyship_label` policies, which have no separate validity window of their own -- they're bound to the shipment's own lifecycle. May also be null for older `external_label` policies that predate this tracking.
    - `claim_valid_from` string, date-time, nullable: Start of the claim window. Null for `easyship_label` policies, which have no separate validity window of their own -- they're bound to the shipment's own lifecycle. May also be null for older `external_label` policies that predate this tracking.
    - `claim_valid_until` string, date-time, nullable: End of the claim window. Null for `easyship_label` policies, which have no separate validity window of their own -- they're bound to the shipment's own lifecycle. May also be null for older `external_label` policies that predate this tracking.
  - `meta` Meta
    - `request_id` string: An unique ID represent the request.

## Other responses

- `202`: Insurance policy request accepted. Awaiting tracking result
- `422`: insufficient balance

## Changes

- **2026-11-03** `b47b54b748a7`: 4 breaking, 13 warning, 14 info
  - the request property `allOf[#/components/schemas/TrackingCreate]/origin_address/contact_name` became not nullable
  - the request property `allOf[#/components/schemas/TrackingCreate]/origin_address/state` became not nullable
  - the response property `insurance_policy/easyship_shipment_id` became nullable for the status `201`
  - the response property `insurance_policy/source` became nullable for the status `201`
  - …27 more

[Operation history](https://skmtc.dev/easyship/apis/easyship-public-api/changes/2024-09/insurances/policies/post.md)

---

[API](https://skmtc.dev/easyship/apis/easyship-public-api.md) - [All operations](https://skmtc.dev/easyship/apis/easyship-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/easyship/apis/easyship-public-api/revisions/b47b54b748a7?raw)