API Endpoints for OAuth Apps

Once your app has an access token for a merchant, these are the calls that are specific to OAuth apps. Summary metrics, attribution, and other data endpoints are in the Triple Whale API reference. They accept the same bearer token, limited to the scopes the merchant granted.

Examples use production. For staging, replace api.triplewhale.com with staging.api.triplewhale.com.

Granted Shops

Returns the shops the merchant consented to for this token.

Bash

curl 'https://api.triplewhale.com/api/v2/developers/oauth2/granted-shops' \
  -H 'Authorization: Bearer <access_token>'

JSON

{
  "accountId": "primary-shop.myshopify.com",
  "additionalShopIds": ["second-shop.myshopify.com"]
}

Field	Meaning
accountId	The primary shop the token was issued for.
additionalShopIds	Any further shops the merchant combined into the same consent. Empty when they connected a single shop.

📘

Older URL

GET /api/v2/users/oauth2/granted-shops still works and returns the same response. New integrations should use /api/v2/developers/oauth2/granted-shops.

Disconnect a Shop

Disconnects one shop the merchant granted. Use this from a "Disconnect Triple Whale" button in your product. It uses the merchant's access token, and it has the same result as the merchant clicking Remove app on Apps: that shop stops sharing, and your app disappears from that shop's Apps page. Every user who connected that shop is disconnected. Other shops on the same consent stay connected.

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/developers/oauth2/disconnect-shop' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"shopId":"<shop_id>"}'

shopId must be accountId, or one of additionalShopIds, from granted shops. Any other shop returns 404.

Call it once per shop. After you disconnect a shop, stop using it with your stored token. If that was the only shop on the consent, delete the token. If other shops remain, keep the token and use it only for those shops. To reconnect a shop, send the merchant through the authorize URL again.

App owners and admins can disconnect a shop by hand in the portal: Usage, Show shops, Disconnect.

Push Ad Data

Apps approved for ads:write can push ad spend and performance rows for a shop. The Quick start card shows this skeleton:

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/data-in/ads' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"shop":"<shop_domain>","data":[]}'

shop must be one of the shops returned by granted shops. The row schema for data is in the Data-In API reference. Rows are attributed to your provider id.

Push Email and SMS Data

Apps approved for email-sms:write can push email, SMS, and direct mail rows for a shop:

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/data-in/email-sms' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"shop":"<shop_domain>","data":[]}'

shop must be one of the shops returned by granted shops. The row schema for data is in Create Email/SMS Record. Rows are attributed to your provider id.

Token Endpoints

Authorize, token, and revoke are covered in Quick Start: The OAuth Flow.

Errors You Will Meet

Status	Typical cause
401	The access token is expired, the merchant removed the app, or the client secret was rotated and a refresh is using the old secret.
403	The token does not have the scope this endpoint needs.
404	disconnect-shop was called with a shop this token did not grant.
429	The rate limit was exceeded.