Sources

Overview

Source profiles let you attach a stable account-owned label and channel definition to raw source_id tags captured from X-Source-ID or future order-import flows.

They do not change VAT calculation results and they do not split your account-wide OSS threshold. Source filters remain analytical reporting slices for reconciliation, drill-down, and accountant review.

All Sources endpoints require a V2 API key. GET endpoints accept full or read-only; write operations require full scope.

Source Key Rules

• 1 to 100 characters
• allowed characters: letters, digits, _, -, /
• use stable store or channel identifiers such as headless-checkout-eu, woocommerce/de, or pos-berlin
• do not include personal data, secrets, customer identifiers, or per-order values

List Source Profiles

GET /v1/sources

Returns all source profiles for the authenticated account together with the active-profile count, the active-profile cap, and the total stored-profile cap.

Example Request

curl https://api.vat-engine.app/v1/sources -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "items": [
    {
      "id": 17,
      "source_key": "headless-checkout-eu",
      "display_name": "Headless EU Checkout",
      "channel_type": "owned_store",
      "platform": "Custom storefront",
      "default_country": "DE",
      "default_currency": "EUR",
      "marketplace_deemed_supplier": false,
      "active": true,
      "created_at": "2026-05-04T11:09:13Z",
      "updated_at": "2026-05-04T11:09:13Z"
    }
  ],
  "activeCount": 1,
  "maxProfiles": 100,
  "storedCount": 1,
  "maxStoredProfiles": 500
}

Create Source Profile

POST /v1/sources

Request Body

Example Request

curl -X POST https://api.vat-engine.app/v1/sources -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{  "source_key": "headless-checkout-eu",  "display_name": "Headless EU Checkout",  "channel_type": "owned_store",  "platform": "Custom storefront",  "default_country": "DE",  "default_currency": "EUR",  "active": true}'

Update Source Profile

PATCH /v1/sources/{id}

Update the profile label, channel metadata, or archive state. source_key is intentionally immutable in this first slice so historical raw tags remain stable.

To clear an optional stored value such as platform, default_country, default_currency, supplier_establishment_country, or dispatch_country, send an empty string for that field. Sending null or omitting the field leaves the existing value unchanged.

Unknown Source Discovery

GET /v1/sources/unknown?limit=100

Returns raw source_id values observed in account transactions that are not yet mapped to a source profile.

Example Response

{
  "items": [
    {
      "source_id": "mobile-checkout",
      "transaction_count": 42,
      "first_seen": "2026-04-01",
      "last_seen": "2026-05-04"
    }
  ]
}