Custom provider (FOCUS)

Custom provider (FOCUS)

Any source · push (API or CSV) · 5 min setup

What is a custom provider?

A custom provider lets you bring spend into StackSpend from any tool that isn't in our built-in list — an internal platform, a niche SaaS, or a vendor we don't yet have a native connector for. Instead of StackSpend pulling the data, you push it: either by POSTing cost rows to our API, or by uploading a CSV in the app and mapping your columns. Once it's in, custom-provider spend flows through the same dashboards, anomaly detection, forecasts and savings as every other provider.

Why it exists

Most teams have long-tail cost sources that never make it into a cost tool, leaving dashboards and budgets incomplete. Custom providers close that gap. The data format is the StackSpend FOCUS Profile — our versioned profile of the FinOps FOCUS 1.2 standard. Because it uses standard FOCUS column names, a FOCUS export from another tool (for example a Vantage custom-provider export) maps straight in.

Set up a custom provider

The FOCUS Profile format

Each row is one charge. Send fully-priced rows — StackSpend stores the cost you provide (we don't price raw usage). Body shape: { "format": "stackspend.focus", "version": "1", "rows": [ … ] }. Both format and version are optional; when you send a version it must be "1", "1.1" or "1.2". Every column below works under any of them — the version records which revision you wrote against, it does not gate anything.

Example request

curl -X POST "https://ingest.stackspend.app/api/v1/public/ingest/focus/YOUR_CONNECTION_ID" \
  -H "Authorization: Bearer YOUR_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "stackspend.focus",
    "version": "1",
    "rows": [
      {
        "ChargePeriodStart": "2026-06-01",
        "ChargePeriodEnd": "2026-06-02",
        "BilledCost": 12.50,
        "EffectiveCost": 12.50,
        "BillingCurrency": "USD",
        "ChargeCategory": "Usage",
        "ServiceName": "Compute",
        "RegionId": "us-east-1",
        "Tags": { "env": "prod" }
      }
    ]
  }'

Re-sending data is safe

Sending the same charge twice does not double-count it. StackSpend derives a stable identity for each row from every column that describes the charge — its charge period, service, resource and SKU, charge category, account and sub-account, region, model, tags, currency and costs — so re-submitting an identical row updates the existing line item instead of creating a second one. Costs are compared by value, so 12.5, "12.50" and "$12.50" are treated as the same charge, and tag order never matters. This makes retries and overlapping date windows safe: a daily job can re-send the trailing week every night without creating duplicates.

Two rows are only merged when every one of those columns matches. Rows that differ by team, region, model or any other dimension stay separate, so a cost-allocation export keeps one line item per team. If you have two charges that are genuinely identical on every column but should stay separate — the same service, day and price billed twice — give each one your own x_stackspend_line_item_id. When that column is present it becomes the identity, so you control exactly what counts as the same charge.

If a charge is restated at a different cost, it is a new line item rather than an update — send a matching negative-cost Adjustment or Credit row if you need the original backed out.

Limits

• 10,000 rows per request — split larger exports into multiple batches.
• ~5 MB request body. Large batches of wide rows can hit this before the row limit; if you receive a 413, send fewer rows per request.
• 60 requests per minute per API key, after which requests return 429 RATE_LIMITED.
• CSV import: the same 10,000-row ceiling, and the uploader accepts files up to 4 MB. Split a larger export and upload the parts — your saved mapping is reused, so each part is two clicks.

Errors you might see

Frequently asked questions