COMPLIANCE API and FORGE Integration

The COMPLIANCE API provides tenant-scoped tariff schedule and calculation endpoints. FORGE or another trusted Velosity service can request a calculation without supplying the item's HTS code or origin; COMPLIANCE obtains those values from the authoritative item record.

Calculate an item tariff

POST /v1/tariffs/calculate
Content-Type: application/json
X-UserID: authenticated-user-id
X-TenantID: active-tenant-id
X-Session-ID: correlation-id

{
  "itemID": "item-123",
  "destinationCountryCode": "RO",
  "customsValue": 123.45,
  "currencyCode": "USD",
  "importDate": "2026-10-02"
}

itemID, destinationCountryCode, and currencyCode are required. customsValue cannot be negative. When importDate is omitted, COMPLIANCE uses the current UTC date.

Successful response

{
  "tariffSetID": "set-id",
  "tariffSetVersionNumber": 1,
  "tariffRuleID": "rule-id",
  "tariffRuleVersionNumber": 1,
  "commodityCode": "8517.62.0070",
  "originCountryCode": "US",
  "destinationCountryCode": "RO",
  "currencyCode": "USD",
  "importDate": "2026-10-02",
  "customsValue": 123.45,
  "dutyRatePercent": 0.0,
  "dutyAmount": 0.0,
  "importTaxRatePercent": 19.0,
  "importTaxAmount": 23.46,
  "totalImportCharges": 23.46,
  "landedValue": 146.91
}

Successful calculations are recorded through the Platform audit and event services.

Error outcomes

Status	Meaning
400 Bad Request	Required input is invalid, the customs value is negative, or the item's origin cannot be resolved.
401 Unauthorized	The user or tenant context is missing or invalid.
404 Not Found	The item does not exist, or no published rule applies. A no-rule response uses code NoApplicableTariffRule.
409 Conflict	Matching rules at the same precedence specify different rates.
500 Internal Server Error	COMPLIANCE or a required upstream service could not complete the request.

Applying the result in FORGE

FORGE remains responsible for the commercial meaning of the returned estimate. A recommended quote or order integration should:

1. Use the line's extended net selling price as customs value unless the organization's customs policy specifies another basis.
2. Use the ship-to country as destination and the quote or order currency as calculation currency.
3. Store the returned monetary values and tariff set/rule versions with the source line.
4. Recalculate after item, quantity, price, currency, destination, or expected import date changes.
5. Keep merchandise subtotal, duty, import tax, and grand total separate so discounts do not reduce tariff charges.
6. Use the Incoterm to decide whether import charges are customer-payable, seller-payable, or informational. For example, DDP normally assigns import responsibility to the seller.

Tariff provenance should remain attached to the item that supplied the HTS code, origin, and customs value. A quote-level tariff total should be derived by summing its line results.

Schedule endpoints

Method	Endpoint	Purpose
GET	/v1/tariffs	List tariff sets.
GET	/v1/tariffs/{setID}	Get a tariff set.
PUT	/v1/tariffs/{setID}	Create or update a Draft set.
POST	/v1/tariffs/{setID}/publish	Publish a Draft set.
POST	/v1/tariffs/{setID}/retire	Retire a Published set.
POST	/v1/tariffs/{setID}/archive	Archive a Draft or Retired set.
GET	/v1/tariffs/{setID}/rules	List rules in a set.
PUT	/v1/tariffs/{setID}/rules/{ruleID}	Create or update a rule in a Draft set.

Security boundary

The API resolves and validates the user and tenant named by the request context. It must be called through a trusted Velosity gateway or internal service that authenticates the caller and controls the identity headers. Do not expose the service directly or allow an external caller to choose arbitrary identity headers.

In a Development environment, interactive Swagger documentation is available at /swagger, with the OpenAPI document at /swagger/v1/swagger.json.