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 and current cap.

Example Request

curl https://api.vat-engine.daily-automations.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
}

Create Source Profile

POST /v1/sources

Request Body

Field	Type	Required	Description
`source_key`	`string`	Yes	Stable key that matches the raw `source_id` you want to map
`display_name`	`string`	Yes	Human-readable label shown in the dashboard
`channel_type`	`string`	Yes	One of `owned_store`, `marketplace`, `subscription`, `pos`, `wholesale`, `test`, `other`
`platform`	`string`	No	Optional platform or integration label
`default_country`	`string`	No	Optional ISO 3166-1 alpha-2 country code
`default_currency`	`string`	No	Optional ISO 4217 currency code
`supplier_establishment_country`	`string`	No	Optional ISO country for the supplier establishment
`dispatch_country`	`string`	No	Optional ISO country for dispatch origin
`marketplace_deemed_supplier`	`boolean`	No	Flags marketplace/deemed-supplier handling for future reporting workflows
`active`	`boolean`	No	Defaults to `true`; inactive profiles stay in history but are archived in selectors

Example Request

curl -X POST https://api.vat-engine.daily-automations.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"
    }
  ]
}

Unknown source tags stay filterable in transaction endpoints even before they are registered. Registering a source profile adds structure and labels; it does not delete or rewrite the raw source evidence already stored in vat_transactions.source_id.

On this page