Pluto Profit
View as Markdown

API reference

The Pluto Profit API exposes the same numbers the dashboard shows over plain REST, plus write endpoints to push orders and costs from any platform. One version track: v1.

Base URL

Every path is relative to the API host. All responses are JSON. Money is always a decimal string, never a JSON number, so nothing is lost to floating-point rounding.

Host
https://api.plutoprofit.com

Authentication

Create an API key at app.plutoprofit.com/developers. The key is shown once.

KindPrefixPowers
Publishablepk_plp_ + 64 hexread-only (read)
Secretsk_plp_ + 64 hexscopes: read, orders:write, costs:write, products:write
Pixel tokenpt_plp_ + 64 hexcollect only: append events to /v1/collect, safe to embed in a page

Keys minted before 2026-07-15 may use the legacy pk_ / sk_ prefix; lookup is hash-based, so they keep working. Send the full key as a bearer token on every request.

A pk_plp_ key on a write route returns 403 with code forbidden_scope (or 401 with an explicit secret-key message). Publishable keys never silently gain write powers.

Request
curl https://api.plutoprofit.com/v1/metrics \
  -H "Authorization: Bearer pk_plp_your_key"

Endpoint map

Read (publishable or secret with read)

  • Name
    GET/v1/metrics
    Description

    Profit metrics for a date range: revenue, costs, ad spend, net profit.

  • Name
    GET/v1/metrics/definitions
    Description

    Metric catalog: what each metric means and how it is calculated.

  • Name
    GET/v1/connections
    Description

    Which sources are connected and when they last synced.

  • Name
    GET/v1/health
    Description
    Service status.
  • Name
    GET/v1/ingest/status
    Description

    What the write API accepted, rejected, and superseded, plus cost coverage.

Write (secret key + scope)

  • Name
    PUT/v1/source
    Description

    Register platform label, shop currency, and IANA timezone before first push.

  • Name
    POST/v1/orders
    Description

    Batch upsert orders with line items and embedded refunds (orders:write).

  • Name
    PUT/v1/products/costs
    Description

    Time-versioned SKU cost catalog (products:write).

  • Name
    POST/v1/costs/spend
    Description

    Per-day custom ad spend into ad_insights_daily (costs:write).

  • Name
    GET|POST|PATCH|DELETE /v1/costs/expenses
    Description

    Recurring expenses over the custom_costs substrate (costs:write).

Collect (pixel token)

  • Name
    POST/v1/collect
    Description

    Browser events from the Pluto pixel, batched, always 204. Authenticated by a pt_plp_ token that can do nothing else.

Full request and response schemas: Metrics, Connections, Orders, Product costs, Costs, Collect, Status, Errors, Rate limits.

Versioning

Path versioning: /v1. Additive-only within v1: new optional fields and new endpoints only. Renames, removals, or semantic changes require /v2.

Unknown request fields are rejected (unknown_field) rather than ignored, so a typo cannot silently drop money.

Money contract

Every money field is a JSON string matching non-negative decimal with at most 6 places, e.g. "149.50". A JSON number in a money position is rejected with money_must_be_string. Pluto never parses money through f64.