Create an Import Cost Estimate

POST /import_cost_estimates

Availability: Public Preview

This endpoint is currently in public preview and available only to approved accounts. Please contact Arta to request access for your organization.

Create an import cost estimate to calculate cross-border duties, fees, and taxes for your international shipments.

Headers

  • Authorization string Required

    Authorize your API calls with an Arta API token

application/json

Body

  • Hide import_cost_estimate attributes Show import_cost_estimate attributes object
    • currency string

      ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

      Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

    • destination object Required

      Details about the destination where it will be imported to

      Hide destination attributes Show destination attributes object
      • city string | null
      • country string Required

        ISO 3166-1 alpha-2 country code of the destination

      • postal_code string | null
      • region string | null

        State, province, or region of the destination. May be required depending on the destination country.

    • end_use string | null

      Optional field specifying the end use of the goods

      Values are for_resale or not_for_resale.

    • objects array[object] Required

      List of objects/items being imported

      Hide objects attributes Show objects attributes object
      • country_of_origin string | null
      • hs_code string Required

        Harmonized System (HS) tariff code for the object

      • quantity number | null

        Quantity of the object

      • reference string | null

        Reference identifier for the object

      • value string Required

        Declared value of the object

      • value_currency string | null Required

        Currency code (ISO 4217) used for the object's declared value

    • origin object Required
      Hide origin attribute Show origin attribute object
      • country string Required

        ISO 3166-1 alpha-2 country code of the origin

    • reference string | null

      Optional reference string for identifying the estimate in your systems

    • transport object Required

      Information about the transport method and cost

      Hide transport attributes Show transport attributes object
      • amount string Required

        Total transport cost

      • amount_currency string | null Required

        Currency code (ISO 4217) for the transport amount (optional)

      • service_level string Required

        Service level for transport (e.g., ups_expedited, fedex_international_first etc). Options are listed in the reference rate service levels metadata endpoint

Responses

  • 201 application/json

    The created Import Cost Estimate

    Hide headers attributes Show headers attributes
    Hide response attributes Show response attributes object
    • currency string

      ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

      Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

    • Details about the destination where it will be imported to

      Hide destination attributes Show destination attributes object
      • city string | null
      • country string

        ISO 3166-1 alpha-2 country code of the destination

      • postal_code string | null
      • region string | null

        State, province, or region of the destination.

    • end_use string | null

      The end use of the goods

      Values are for_resale or not_for_resale.

    • estimate object

      Breakdown of the estimated import costs

      Hide estimate attributes Show estimate attributes object
      • line_items array[object]

        Detailed breakdown of individual charges

        Hide line_items attributes Show line_items attributes object
        • amount string

          Amount of the charge in the estimate currency

        • Description of the charge

        • subtype string

          Subtype classification of the charge

        • type string

          Type of charge (e.g., duty, tax, fee)

      • summary object

        Summary totals of the import cost estimate

        Hide summary attributes Show summary attributes object
    • id string(uuid)

      Unique identifier for the import cost estimate

    • objects array[object]

      List of objects/items being imported

      Hide objects attributes Show objects attributes object
      • country_of_origin string | null

        ISO 3166-1 alpha-2 country code where the object originated

      • hs_code string

        Harmonized System (HS) tariff code for the object

      • quantity number | null

        Quantity of the object

      • reference string | null

        Reference identifier for the object

      • value string

        Declared value of the object

      • value_currency string | null

        Currency code (ISO 4217) used for the object's declared value

    • origin object

      Details about the origin location

      Hide origin attribute Show origin attribute object
      • country string

        ISO 3166-1 alpha-2 country code of the origin

    • reference string | null

      Reference string for identifying the estimate in your systems

    • Short automatically generated reference code for the identifying import cost estimate in Arta's system

    • status string

      Status of the import cost estimate calculation

      Values are failed or success.

    • Information about the transport method and cost

      Hide transport attributes Show transport attributes object
      • amount string

        Total transport cost

      • amount_currency string | null

        Currency code (ISO 4217) for the transport amount

      • Service level for transport (e.g., ups_expedited, fedex_international_first etc). Options are listed in the reference rate service levels metadata endpoint

  • 400 application/json

    Bad Request

    Hide headers attributes Show headers attributes
    Hide response attribute Show response attribute object
    • errors object
      Hide errors attribute Show errors attribute object
POST /import_cost_estimates
curl \
 --request POST 'https://api.arta.io/import_cost_estimates' \
 --header "Content-Type: application/json" \
 --header "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 --data '{"import_cost_estimate":{"origin":{"country":"US"},"objects":[{"value":"10869.45","hs_code":"691390","reference":"ceramic-vase-maria-lundqvist"}],"currency":"USD","transport":{"amount":"20000","service_level":"ups_expedited"},"destination":{"region":"ON","country":"CA"}}}'
Request example
{
  "import_cost_estimate": {
    "origin": {
      "country": "US"
    },
    "objects": [
      {
        "value": "10869.45",
        "hs_code": "691390",
        "reference": "ceramic-vase-maria-lundqvist"
      }
    ],
    "currency": "USD",
    "transport": {
      "amount": "20000",
      "service_level": "ups_expedited"
    },
    "destination": {
      "region": "ON",
      "country": "CA"
    }
  }
}
Response examples (201)
{
  "id": "30e1d8e7-f175-46c7-afee-8aa16c9d988b",
  "origin": {
    "country": "BR"
  },
  "status": "success",
  "end_use": "for_resale",
  "objects": [
    {
      "value": "10869.45",
      "hs_code": "691390",
      "quantity": 1,
      "reference": "ceramic-vase-maria-lundqvist",
      "value_currency": "USD",
      "country_of_origin": null
    }
  ],
  "currency": "USD",
  "estimate": {
    "summary": {
      "fees": "147.13",
      "taxes": "1754.97",
      "duties": "2119.53"
    },
    "line_items": [
      {
        "type": "duty",
        "amount": "706.51",
        "subtype": "item",
        "description": "duty"
      }
    ]
  },
  "reference": null,
  "shortcode": "JANANI-I5Y6SR",
  "transport": {
    "amount": "20000.00",
    "service_level": "ups_expedited",
    "amount_currency": "USD"
  },
  "destination": {
    "city": null,
    "region": "ON",
    "country": "CA",
    "postal_code": null
  }
}
Response examples (400)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "errors": {
    "detail": "string"
  }
}