Customs data

What customs trade data you can query, the request parameters and limits, how per-row billing works, and what happens when the source is unavailable.

Last updated 2026-10-23

Customs queries are available through the REST API and MCP. You can query import and export records by company, product, HS code and country. This page lists the seven queries, the request parameters and the billing rules; unit prices live in How credits are charged.

What you can query

Query	Returns	Endpoint
Company name resolution	Matching companies, how many records each has, latest trade date (free)	`POST /v1/customs/company-candidates`
Discover companies	Companies filtered by importer or exporter role, product, HS code, country and dates, with trade totals	`POST /v1/customs/discover-companies`
Counterparties	The trading counterparties of one company	`POST /v1/customs/counterparties`
HS category mix	Trade share by HS category for one company	`POST /v1/customs/categories`
Trade trends	Trade value and volume by month, quarter or year	`POST /v1/customs/trend`
Origin and destination countries	Country mix for one company's imports or exports	`POST /v1/customs/countries`
Full report	Counterparties, categories, trends and countries combined into one report	`POST /v1/customs/full-report`

The MCP server exposes the same seven queries. Tool names share one prefix and contain the query name, such as customs_counterparties.

Request parameters

Parameter	Meaning
`name` (company name resolution) or `companyName` (other queries)	Company name, up to 512 characters
`role` (company name resolution) or `companyRole` (other queries)	`importer` or `exporter`
`startDate`, `endDate`	`YYYY-MM-DD`; the span cannot exceed 365 days
`hsCode`	One HS code of 2, 4, 6, 8 or 10 digits
`product`, `productDescription`	Product description, up to 256 characters
`originCountryCode`, `destinationCountryCode`	ISO 3166-1 alpha-3 country code, uppercase, for example `CHN` or `DEU`
`filters`	Filter object for company-level queries: `hsCode`, `productDescription`, `originCountryCode`, `destinationCountryCode`
`periodUnit`	Trends only: `month`, `quarter` or `year`
`page`, `pageSize`	`page` 1–1000; `pageSize` 1–20
`sortBy`, `sortOrder`	`trade_count`, `amount_usd`, `quantity`, `weight`; `desc` or `asc`

Invalid input returns 400 with code set to invalid_request.

Billing

Company name resolution is free.
Every other query is billed per returned row; a query that returns no rows costs nothing.
Before a query, credits are held for pageSize rows; the full report holds for each of its four sections. Settlement uses the rows actually returned, and the excess hold is returned.
Billable queries require an Idempotency-Key header, or the idempotency_key argument on MCP tools. A retry with the same key is not charged twice.
Not enough credits returns 402 with code set to insufficient_credits.

Results

The paged row queries (discover companies, counterparties, categories, trends and countries) return status, page, pageSize, totalRows, hasMore, costUnits, latencyMs and provenance. Company name resolution returns a candidates list with status, costUnits, latencyMs and provenance. The full report returns its four sections plus the company, dates, costUnits, latencyMs and provenance.

costUnits is the number of rows billed for that call. Each row carries provenance so you can check where the data came from.

When it is unavailable

If the data source is not configured or is temporarily unavailable, the API returns 503 (provider_unavailable) or 502, and charges nothing.
In a Target's search plan, the Customs records channel shows Unavailable when the channel is not enabled or the data source is unavailable. It cannot be switched on, so it costs nothing.
The full report is fetched in one call across four dimensions; if that call fails, the whole hold is returned.

Examples

Company name resolution (free):

curl "https://www.renewsell.com/v1/customs/company-candidates" \
  -H "Authorization: Bearer $RENEWSELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Siemens","role":"exporter"}'

Trends (billable, idempotency key required):

curl "https://www.renewsell.com/v1/customs/trend" \
  -H "Authorization: Bearer $RENEWSELL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trend-2026-10-23-001" \
  -d '{"companyName":"Siemens","companyRole":"exporter","startDate":"2026-01-01","endDate":"2026-10-01","filters":{},"periodUnit":"month","page":1,"pageSize":20}'

PreviousWebhooks NextFAQ