Quickstart

TLL answers decision questions about territorial rules. This page gets you from zero to one working POST /v1/checkout/resolve call.

1. Get an API key

Sign up with your email at app.territoriallogicallayer.com/app/signup. A test-mode key prefixed tll_test_ is generated on first login. Keys are visible exactly once, copy it immediately.

2. Set an environment variable

export TLL_KEY=tll_test_a1b2...xy9z

3. Resolve your first checkout

curl https://api.territoriallogicallayer.com/v1/checkout/resolve \
  -H "Authorization: Bearer $TLL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seller": { "tll_code": "DE", "vat_registered_in": ["DE"] },
    "buyer":  { "address": { "postal_code": "22100", "city": "Mariehamn", "country_input": "FI" } },
    "cart":   [{ "sku": "hoodie-01", "quantity": 1, "unit_price_eur": "49.00", "goods_type": "physical" }],
    "context": { "channel": "web", "payment_methods_offered": ["card"] }
  }'

Expected response (trimmed):

{
  "mode": "test",
  "disclaimer": "Test data. Illustrative only. Not authoritative. Upgrade to an enterprise key for live data.",
  "checkout": {
    "buyer_tll_code": "AX",
    "address_classification_confidence": "medium",
    "address_conflict": true,
    "tax": {
      "outbound_vat_rate": "0",
      "outbound_vat_reason": "Export to non-EU VAT territory",
      "import_vat_note": "Recipient pays governing state's VAT rate on import.",
      "invoice_requirements": { "mark_as_export": true, "buyer_vat_id_required": false }
    },
    "logistics": {
      "recommended_route": "DIRECT",
      "stops": ["DE", "AX"],
      "customs_declaration_required": true,
      "customs_forms": ["CN22"],
      "estimated_transit_bucket": "3-5_business_days"
    },
    "warnings": [
      "Address signals indicate AX but country_input was FI",
      "Do NOT route via Finnish domestic postal system; AX requires export declaration."
    ],
    "_test_mode": true
  },
  "sources": [],
  "meta": { "request_id": "req_…" }
}

Test mode vs live

Developer-tier keys are test-mode only. Responses are identical in shape to live mode so integration code needs no changes, but values carry [TEST MODE] markers and rates are rounded to obvious mock values. For live data, contact sales.