Skip to content

Instantly share code, notes, and snippets.

@att14

att14/.gitignore

Forked from victoryftw/classifications-api.md
Last active May 4, 2020 18:01
Show Gist options
  • Save att14/add2bbbbc6e3f65f85a4f5a3b6b92922 to your computer and use it in GitHub Desktop.
Save att14/add2bbbbc6e3f65f85a4f5a3b6b92922 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": null,
      "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": null,
      "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": null,
      "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": null,
      "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": null,
      "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": null,
      "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"
  ]
}
Display the source blob
Display the rendered blob
Raw
Ξclassifications-api.pdf
View raw
Display the source blob
Display the rendered blob
Raw
Ξduties-and-taxes-api.pdf
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment