API reference

Pluto Profit

The Pluto Profit connection: one store per workspace, read only.

GET/integrations/pluto-profit

Get the Pluto Profit connection

Whether a Pluto Profit store is connected, how (method: oauth, approved in Pluto Profit, or apiKey), which store (name, Shopify domain, currency, channels), who connected it and when, and how current the store's data is. statusReason says why a reauthorize connection needs reconnecting. A connected store is re-checked at Pluto Profit every few minutes when read. Not for guests.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

checkedAtstring (date-time) or null
When Pluto Profit last confirmed the connection and store.
connectedAtstring (date-time) or null
Connected.
connectedBystring (uuid) or null
The person who connected it.
connectedByNamestring or null
The person who connected it, by name.
keyHintstring or null
The key's last four characters.
keyKindstring or null
The API key's kind (a publishable key reads only).One of publishable, secret
methodstring or null
How it's connected: oauth (a person approved access in Pluto Profit) or apiKey (a pasted key).One of oauth, apiKey
oauthAvailableboolean
Connecting by approving in Pluto Profit (connect_pluto_profit) is set up here.
statusstringRequired
reauthorize: Pluto Profit no longer accepts the approval or key (statusReason says why); a person reconnects (reconnect_pluto_profit), or an admin pastes a new key in Integrations.One of connected, reauthorize, disconnected
statusReasonstring or null
Why it needs attention.
storeobject or null
The connected store; null when disconnected.
store.channelsarray of objectsRequired
The store's channels in Pluto Profit.
store.channels[].channelstringRequired
shopify, meta, google, …
store.channels[].lastSyncedAtstring or null
Its last sync in Pluto Profit.
store.channels[].statusstringRequired
Pluto Profit's status for it (connected, needs_reauth, …).
store.currencystring or null
The store's reporting currency (ISO 4217); every Pluto Profit amount is in it.
store.idstring or null
Pluto Profit's ID for the store.
store.namestringRequired
The store's name in Pluto Profit, else its Shopify domain, or "Pluto Profit store".
store.shopDomainstring or null
Shopify domain.
syncedThroughstring (date) or null
The latest day with synced store data in Pluto Profit.
versionintegerRequired
Increments on every change.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/integrations/pluto-profit" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/integrations/pluto-profit/authorize

Start connecting Pluto Profit

Returns Pluto Profit's approval URL for a person to open in their browser; nothing connects until they approve in Pluto Profit. Give the URL to the person the credential acts for: they must be signed in to Pluto Ads as themselves when they open it. The URL works once, for 15 minutes. reconnect: true approves again for an existing connection (status reauthorize, another store, or moving from an API key). Needs a credential that acts for a person (a connected agent or an mcp agent client; an API key gets 403). 409 when Pluto Profit is already connected (connect) or isn't (reconnect), or when approving in Pluto Profit isn't set up (oauthAvailable: false; connect with an API key instead). The same command as MCP connect_pluto_profit and reconnect_pluto_profit.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

reconnectboolean
Approve again for an existing connection instead of connecting.
returnTostring
Where the app opens after the approval, a path such as /integrations (the default).

Response201 Created

authorizationUrlstringRequired
Pluto Profit's approval for the person to open in their browser (single use).
expiresAtstring (date-time)Required
The URL stops working after this.
personIdstring (uuid) or nullRequired
The person who must open the URL, signed in to Pluto Ads.
statusstringRequired
The connection's status before the approval.One of connected, reauthorize, disconnected

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Pluto Profit is already connected, isn't connected (reconnect), or approving isn't set up.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/pluto-profit/authorize" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 999fc24e-70e7-4950-8d18-bbd5a97bfe86" \
  -H "Content-Type: application/json" \
  -d '{
    "reconnect": true,
    "returnTo": "/settings/billing"
  }'
POST/integrations/pluto-profit/connect

Connect Pluto Profit with an API key

The API-key way to connect. Verifies the key with Pluto Profit, then stores it encrypted and connects its store to the workspace, replacing an earlier store or approval. The key is never returned, logged or kept in receipts; only its last four characters are shown. 422 when Pluto Profit doesn't accept the key.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

apiKeystringRequired
The store's Pluto Profit API key (pk_plp_… or sk_plp_…; Pluto Profit, Developers). A publishable key is enough: Pluto Ads only reads.

Response200 OK

checkedAtstring (date-time) or null
When Pluto Profit last confirmed the connection and store.
connectedAtstring (date-time) or null
Connected.
connectedBystring (uuid) or null
The person who connected it.
connectedByNamestring or null
The person who connected it, by name.
keyHintstring or null
The key's last four characters.
keyKindstring or null
The API key's kind (a publishable key reads only).One of publishable, secret
methodstring or null
How it's connected: oauth (a person approved access in Pluto Profit) or apiKey (a pasted key).One of oauth, apiKey
oauthAvailableboolean
Connecting by approving in Pluto Profit (connect_pluto_profit) is set up here.
statusstringRequired
reauthorize: Pluto Profit no longer accepts the approval or key (statusReason says why); a person reconnects (reconnect_pluto_profit), or an admin pastes a new key in Integrations.One of connected, reauthorize, disconnected
statusReasonstring or null
Why it needs attention.
storeobject or null
The connected store; null when disconnected.
store.channelsarray of objectsRequired
The store's channels in Pluto Profit.
store.channels[].channelstringRequired
shopify, meta, google, …
store.channels[].lastSyncedAtstring or null
Its last sync in Pluto Profit.
store.channels[].statusstringRequired
Pluto Profit's status for it (connected, needs_reauth, …).
store.currencystring or null
The store's reporting currency (ISO 4217); every Pluto Profit amount is in it.
store.idstring or null
Pluto Profit's ID for the store.
store.namestringRequired
The store's name in Pluto Profit, else its Shopify domain, or "Pluto Profit store".
store.shopDomainstring or null
Shopify domain.
syncedThroughstring (date) or null
The latest day with synced store data in Pluto Profit.
versionintegerRequired
Increments on every change.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/pluto-profit/connect" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 74e3adb7-901b-4015-92c9-e1d029af8346" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "sk_EBOPMPuUHAnWrzaAHMeyUXjfYddSmE21"
  }'
POST/integrations/pluto-profit/disconnect

Disconnect Pluto Profit

Revokes the approval's tokens at Pluto Profit when it can, then deletes the stored approval tokens or key and cached figures. The approval stays listed in Pluto Profit (Settings, Connected apps) until removed there; a key keeps working until revoked there (Developers).

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

checkedAtstring (date-time) or null
When Pluto Profit last confirmed the connection and store.
connectedAtstring (date-time) or null
Connected.
connectedBystring (uuid) or null
The person who connected it.
connectedByNamestring or null
The person who connected it, by name.
keyHintstring or null
The key's last four characters.
keyKindstring or null
The API key's kind (a publishable key reads only).One of publishable, secret
methodstring or null
How it's connected: oauth (a person approved access in Pluto Profit) or apiKey (a pasted key).One of oauth, apiKey
oauthAvailableboolean
Connecting by approving in Pluto Profit (connect_pluto_profit) is set up here.
statusstringRequired
reauthorize: Pluto Profit no longer accepts the approval or key (statusReason says why); a person reconnects (reconnect_pluto_profit), or an admin pastes a new key in Integrations.One of connected, reauthorize, disconnected
statusReasonstring or null
Why it needs attention.
storeobject or null
The connected store; null when disconnected.
store.channelsarray of objectsRequired
The store's channels in Pluto Profit.
store.channels[].channelstringRequired
shopify, meta, google, …
store.channels[].lastSyncedAtstring or null
Its last sync in Pluto Profit.
store.channels[].statusstringRequired
Pluto Profit's status for it (connected, needs_reauth, …).
store.currencystring or null
The store's reporting currency (ISO 4217); every Pluto Profit amount is in it.
store.idstring or null
Pluto Profit's ID for the store.
store.namestringRequired
The store's name in Pluto Profit, else its Shopify domain, or "Pluto Profit store".
store.shopDomainstring or null
Shopify domain.
syncedThroughstring (date) or null
The latest day with synced store data in Pluto Profit.
versionintegerRequired
Increments on every change.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/pluto-profit/disconnect" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 6fa66dff-e2f4-431d-9555-ac4a57f3110c"
POST/integrations/pluto-profit/verify

Check a Pluto Profit key

Asks Pluto Profit which store the key belongs to, without storing anything: a key belongs to exactly one store, so choosing the store is choosing its key. alsoConnectedTo names other workspaces of the organization already connected to it. 422 when Pluto Profit doesn't accept the key.

Permission: admin

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

apiKeystringRequired
The store's Pluto Profit API key (pk_plp_… or sk_plp_…; Pluto Profit, Developers). A publishable key is enough: Pluto Ads only reads.

Response200 OK

alsoConnectedToarray of stringsRequired
Other workspaces of the organization already connected to this store.
keyHintstringRequired
The key's last four characters.
keyKindstringRequired
The key's kind.One of publishable, secret
storeobjectRequired
store.channelsarray of objectsRequired
The store's channels in Pluto Profit.
store.channels[].channelstringRequired
shopify, meta, google, …
store.channels[].lastSyncedAtstring or null
Its last sync in Pluto Profit.
store.channels[].statusstringRequired
Pluto Profit's status for it (connected, needs_reauth, …).
store.currencystring or null
The store's reporting currency (ISO 4217); every Pluto Profit amount is in it.
store.idstring or null
Pluto Profit's ID for the store.
store.namestringRequired
The store's name in Pluto Profit, else its Shopify domain, or "Pluto Profit store".
store.shopDomainstring or null
Shopify domain.
syncedThroughstring (date) or null
The latest day with synced store data.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/pluto-profit/verify" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "sk_EBOPMPuUHAnWrzaAHMeyUXjfYddSmE21"
  }'