Skip to content

Instantly share code, notes, and snippets.

@victoryftw

victoryftw/classifications-api.md

Last active May 4, 2020 17:50
Show Gist options
  • Save victoryftw/7ec8e1d9e8ad18a7d15d93a63feef9f2 to your computer and use it in GitHub Desktop.
Save victoryftw/7ec8e1d9e8ad18a7d15d93a63feef9f2 to your computer and use it in GitHub Desktop.
Download ZIP
EasyPost Duties and Taxes API Documentation
Raw
classifications-api.md

EasyPost Duties and Taxes API

Classification

A Classification identifies a good to be shipped based on its description.

name type source description
id string easypost unique identifier
description string user description of the classified product
hs_code string easypost the HS6 code associated with the product
transport_code string easypost the transportation prohibition and restriction codes relating to the product
export_code string easypost the export prohibition and restriction codes relating to the product 
{
  "id": "cls_e68f485c26ea455892195e55b03af0ef",
  "description": "shoe cloth",
  "hs_code": "630710",
  "transport_code": "TG002",
  "export_code": "ED023"
}

POST /v1/classifications

Input

name required description
description * description of the product to be classified

Example

curl -X POST "https://api.easypost.com/duties_and_taxes/v1/classifications" \
  -u "<YOUR_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "oxford shoe"
  }'

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "id": "cls_e68f485c26ea455892195e55b03af0ef",
  "description": "shoe cloth",
  "hs_code": "630710",
  "transport_code": "TG002",
  "export_code": "ED023"
}

Example Invalid Reuqest

curl -X POST "https://api.easypost.com/duties_and_taxes/v1/classifications" \
  -u "<YOUR_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
    "not-the-description": "oxford shoe"
  }'

Response

HTTP/1.1 422 UnprocessableEntity
Content-Type: application/json; charset=utf-8
{
  "errors": [
    "description: Required"
  ]
}
Raw
duties-and-taxes-api.md

EasyPost Duties and Taxes API

Duties and Taxes

A Duties and Taxes response includes both the itemized and aggregate taxes and duties levied on a shipment

name type source description
products Array of Products user A JSON array of the items in the customer’s package, defined below
product_raw_total decimal easypost the total of all products submitted without duty and tax applied
tax_total decimal easypost the total tax payable for the products, shipping and insurance
duty_total decimal easypost the total duty payable for the products, shipping and insurance
total decimal easypost the total price including shipping and insurance
tax_deminimis_value decimal easypost the value for duty deminimis
duty_deminimis_value decimal easypost the value for tax deminimis
recipient_score_calculated decimal easypost the score calculated for the supplied recipient
recipient_lists_matched decimal easypost the total number of list(s) the match was found in
recipient_matches Array of Matches easypost the total number of list(s) the match was found in

Product

name type source description
classification_id string user id returned by the classification API for the given product
value decimal user the unit price of the product being calculated, without a currency symbol
tax_rate decimal easypost the percentage tax rate for the product in the destination country
tax_value decimal easypost the value of the tax payable on the product
duty_rate decimal easypost the percentage duty rate for the product in the destination country
duty_value decimal easypost the value of the duty payable on the product
hs_code string easypost the HS6 code associated with the product
tariff_code string easypost the 6+ digit code associated with the item in the destination country – if available – if not available then ‘0000’ may be appended to the right of the HS6 code

Match

name type source description
score_calculated decimal easypost the score calculated for the user
name_match boolean easypost whether the name was a good match, independent of address
partial_name_match boolean easypost whether only certain parts of the name were a match, or if there was an initial passed through for the first or middle names, whether that was matched to a name, independent of address
ordered_name_match boolean easypost whether the elements of the name were matched but in the wrong order, for example John Joseph would ordered_name_match Joseph John independent of address.
address_match boolean easypost whether the address was a match, independent of name
partial_address_match boolean easypost whether some of the address elements were a match, independent of name
place_of_birth string easypost the place of birth of the person – if matched on name and if the data is available
affiliated_countries Array of strings easypost list of countries that the name match is associated with, independent of supplied address
match_type string easypost whether a Country, a Corporation or an Individual (if present)
lists_matched Array of strings easypost which list(s) the match was scored against 
{
  "products": [
    {
      "classification_id": "cls_0ac0749ce2aa40de9e076db9ffeba55a",
      "value": 15.63,
      "tax_rate": 0,
      "tax_value": 0,
      "duty_rate": 0.08,
      "duty_value": 1.25,
      "hs_code": "640359",
      "tariff_code": "6403599900"
    },
    {
      "classification_id": "cls_32e942c885014fd795f318dc62ca5c2c",
      "value": 12.21,
      "tax_rate": 0.2,
      "tax_value": 2.64,
      "duty_rate": 0.08,
      "duty_value": 0.98,
      "hs_code": "640359",
      "tariff_code": "6403599900"
    }
  ],
  "product_raw_total": 27.84,
  "tax_total": 2.64,
  "duty_total": 2.23,
  "total": 32.71,
  "tax_deminimis_value": 15,
  "duty_deminimis_value": 135,
  "recipient_score_calculated": 15,
  "recipient_lists_matched": 2,
  "recipient_matches": [
    {
      "score_calculated": 15,
      "name_match": False,
      "partial_name_match": False,
      "ordered_name_match": False,
      "address_match": False,
      "partial_address_match": False,
      "place_of_birth": "",
      "affiliated_countries": None,
      "lists_matched": ["GREAT BRITAIN (UK) - HM TREASURYS CONSOLIDATED LIST OF FINANCIAL SANCTIONS TARGETS IN THE UK-THE ISIL (DA\"ESH) AND AL-QAIDA ORGANISATIONS"],
      "match_type": "Entity"
    },
    {
      "score_calculated": 15,
      "name_match": False,
      "partial_name_match": False,
      "ordered_name_match": False,
      "address_match": False,
      "partial_address_match": False,
      "place_of_birth": "",
      "affiliated_countries": None,
      "lists_matched": ["US - BIS - PARTIES OF CONCERN"],
      "match_type": "Individual"
    },
    {
      "score_calculated": 15,
      "name_match": False,
      "partial_name_match": False,
      "ordered_name_match": False,
      "address_match": False,
      "partial_address_match": False,
      "place_of_birth": "",
      "affiliated_countries": None,
      "lists_matched": ["US - BIS - PARTIES OF CONCERN"],
      "match_type": "Entity"
    }
  ]
}

POST /v1/duties_and_taxes

Input

name required description
from_address * an EasyPost Address construct indicating at least the country from which the shipment is originating
to_address * an EasyPost Address construct indicating the address to which the shipment is destined. This is expected to include country, recipient name, street address, state/county, and postal code
shipping_price * a decimal value indicating the value of the transportation associated with the purchase, without a currency symbol
products * a JSON array of the items in the customer’s package, defined below

Input - Product

name required description
classification_id id returned by the classification API for the given product
value * the unit price of the product being calculated, without a currency symbol
quantity * the quantity of the product being shipped
weight * weight of the product in grammes
volume * volume of the product in milliliters
hs_code volume of the product in milliliters
description description of the product

note: either classification_id or a combination of hs_code and description must be provided.

Example

curl -X POST "https://api.easypost.com/duties_and_taxes/v1/duties_and_taxes" \
  -u "<YOUR_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address": {
      "name": "",
      "company": "EasyPost",
      "street1": "345 California Street",
      "street2": "Floor 10",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94104",
      "country": "US",
      "email": "[email protected]",
      "phone": "555-555-5555"
    },
    "to_address": {
      "name": "Sir Royal MailMan",
      "company": "Royal Mail Group",
      "street1": "100 Victoria Embankment",
      "street2": "Floor 10",
      "city": "London",
      "state": "JS",
      "zip": "EC4Y 0HQ",
      "country": "GB",
      "email": "[email protected]",
      "phone": "555-555-5555"
    },
    "shipping_price": 14.99,
    "products": [
      {
        "classification_id": "cls_0ac0749ce2aa40de9e076db9ffeba55a",
        "value": 5.21,
        "quantity": 3,
        "weight": 700,
        "volume": 700
      },
      {
        "classification_id": "cls_32e942c885014fd795f318dc62ca5c2c",
        "value": 12.21,
        "quantity": 1,
        "weight": 1200,
        "volume": 800
      }
    ]
  }'

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "products": [
    {
      "classification_id": "cls_0ac0749ce2aa40de9e076db9ffeba55a",
      "value": 15.629999999999999,
      "tax_rate": 0,
      "tax_value": 0,
      "duty_rate": 0.08,
      "duty_value": 1.25,
      "hs_code": "640359",
      "tariff_code": "6403599900"
    },
    {
      "classification_id": "cls_32e942c885014fd795f318dc62ca5c2c",
      "value": 12.21,
      "tax_rate": 0.2,
      "tax_value": 2.64,
      "duty_rate": 0.08,
      "duty_value": 0.98,
      "hs_code": "640359",
      "tariff_code": "6403599900"
    }
  ],
  "product_raw_total": 27.84,
  "tax_total": 2.64,
  "duty_total": 2.23,
  "total": 32.71,
  "tax_deminimis_value": 15,
  "duty_deminimis_value": 135,
  "recipient_score_calculated": 15,
  "recipient_lists_matched": 2,
  "recipient_matches": [
    {
      "score_calculated": 15,
      "name_match": False,
      "partial_name_match": False,
      "ordered_name_match": False,
      "address_match": False,
      "partial_address_match": False,
      "place_of_birth": "",
      "affiliated_countries": None,
      "lists_matched": ["GREAT BRITAIN (UK) - HM TREASURYS CONSOLIDATED LIST OF FINANCIAL SANCTIONS TARGETS IN THE UK-THE ISIL (DA\"ESH) AND AL-QAIDA ORGANISATIONS"],
      "match_type": "Entity"
    },
    {
      "score_calculated": 15,
      "name_match": False,
      "partial_name_match": False,
      "ordered_name_match": False,
      "address_match": False,
      "partial_address_match": False,
      "place_of_birth": "",
      "affiliated_countries": None,
      "lists_matched": ["US - BIS - PARTIES OF CONCERN"],
      "match_type": "Individual"
    },
    {
      "score_calculated": 15,
      "name_match": False,
      "partial_name_match": False,
      "ordered_name_match": False,
      "address_match": False,
      "partial_address_match": False,
      "place_of_birth": "",
      "affiliated_countries": None,
      "lists_matched": ["US - BIS - PARTIES OF CONCERN"],
      "match_type": "Entity"
    }
  ]
}

Example Invalid Reuqest

curl -X POST "https://api.easypost.com/duties_and_taxes/v1/duties_and_taxes" \
  -u "<YOUR_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
    "shipper_city": "oxford shoe"
  }'

Response

HTTP/1.1 422 UnprocessableEntity
Content-Type: application/json; charset=utf-8
{
  "errors": [
    "from_address: Required",
    "shipping_price: Required",
    "to_address: Required"
  ]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment