Customs

Search TARIC codes by description or code. Use the result as the HS code of an item in the customs data of an international shipment.

GET/tariff-codes

Search TARIC codes by description

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Assisted lookup of TARIC / HS codes from a natural-language product description (Italian or English). Only codes present in the customs catalogue are returned. Use the code as customs.items[].hs_code in POST /shipments. This search does not provide quantity, value, weight or export reason. If nothing matches, try a more specific description or English.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    q
    Type
    string
    required
    Description

    Product description.

  • Name
    lang
    Type
    string
    Description

    Search language.

    Allowed values: it, en. Default: it.

  • Name
    limit
    Type
    integer
    Description

    Maximum results, 1 to 10.

    Default: 5. ≥ 1, ≤ 10.

Responses

  • 200Matches, best first.TariffCodeList
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/tariff-codes
Loading...

Response 200

{
  "data": [
    {
      "tariff_code": "1905310000",
      "descriptions": {
        "it": "Biscotti dolci",
        "en": "Sweet biscuits"
      },
      "confidence": 0.92
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 5
  }
}

Models

Objects used by the requests and responses on this page.

ParceLabsVersion

CorrelationId

KeyLocale

TariffCodeList

TariffCode

  • Name
    tariff_code
    Type
    string
    required
    Italian alias: taric_code
    Description

    10-digit TARIC code. Use it as customs.items[].hs_code.

  • Name
    descriptions
    Type
    object
    required
    Italian alias: descrizioni
    Description

    Official descriptions.

  • Name
    confidence
    Type
    number
    Italian alias: confidence
    Description

    Estimated match score, results sorted descending.

    ≥ 0, ≤ 1.

PageMeta

Pagination metadata.

  • Name
    total
    Type
    integer
    required
    Description

    Total number of items matching the filters.

  • Name
    page
    Type
    integer
    required
    Description

    Current page, starting at 1.

  • Name
    per_page
    Type
    integer
    required
    Description

    Items per page.

BadRequest

Unauthorized

Forbidden

Gone

TooManyRequests

ServerError

BadGateway

Was this page helpful?