Stripe

Previous Next

Connect Stripe

Squoosh reads your order count from succeeded Stripe PaymentIntents. It does not yet change how your AI shoppers behave. This page covers the connection available from Integrations.

Beta: credential-ready

This connector has not been validated against a live account or a Stripe sandbox. It remains at the auth stage. The parser is tested with documented response fixtures; that does not establish live compatibility.

What the connection does

The connection records the number of PaymentIntents with a succeeded status created during the selected window. A PaymentIntent represents a payment flow, so this is a payment count used as an order-count source, not a count of unique customers or store checkout orders.

Stripe does not provide website sessions through these endpoints. Squoosh therefore records the count, including a genuine zero, without calculating a conversion rate. Device, geography, and traffic-source distributions are unavailable. Connecting Stripe does not yet calibrate your AI shoppers or change their behavior.

Connect Stripe

You need a restricted API key for the Stripe account whose payments you want to count. There is no site ID, currency filter, or Stripe Connect account selector.

  1. In the Stripe Dashboard, open Developers → API keys.
  2. Choose Create restricted key. Name it for Squoosh and set PaymentIntents to Read. Leave unrelated permissions at None. Squoosh does not call Balance or Charges endpoints.
  3. Copy the key when Stripe reveals it. Use an rk_live_ key for live payments or an rk_test_ key for sandbox payments. A broad sk_ secret key also works, but a restricted key limits access. A pk_ publishable key cannot read payments.
  4. In Squoosh, open Integrations, choose Stripe, and click Connect.
  5. Paste the key into Restricted API key and click Connect.

The verification request lists one PaymentIntent. An empty account can still verify successfully. Sandbox keys produce test-data counts and are identified as test mode. PaymentIntents Read access to the Search endpoint still needs validation with a restricted key; a permission error is reported rather than hidden.

See Stripe's API keys guide and restricted-key instructions for key creation and rotation.

What Squoosh reads and never reads

Data Use
Search total_count The full matching payment count while it is below 10,000.
PaymentIntent ID, status, and creation timestamp Count distinct succeeded payments during paginated reads. IDs are temporary pagination/deduplication data, not snapshot fields.
livemode Identify sandbox data.
Count, window length, retrieval time, and completeness warnings The aggregate snapshot Squoosh stores.

Squoosh never requests customer, balance, charge, or payment-method endpoints and never creates, updates, refunds, or cancels payments. Stripe's PaymentIntent response can include amounts, addresses, metadata, customer references, and a sensitive client_secret. The adapter discards these fields; it never stores raw PaymentIntent objects, uses addresses to infer geography, or sums revenue. The API key travels only in the authorization header, and provider error details and response identifiers are discarded.

Limits and caveats

  • Full UTC days: the window starts at midnight UTC N days ago and ends just before midnight UTC today. The current incomplete day is excluded. Both Search and List use these bounds.
  • Creation time, not success time: a payment created before the window and completed inside it is excluded. A payment created inside the window can count when its status later becomes succeeded.
  • Refunds and disputes remain counted. PaymentIntents can remain succeeded after either. Recurring subscription/invoice payments also count. Legacy payments without a PaymentIntent do not count.
  • Search freshness: the index normally updates within a minute and can lag by up to an hour during outages. Snapshots carry a retrieval timestamp and a search-lag warning; they are not real-time payment reports.
  • Search ceiling: Stripe only guarantees total_count accuracy up to 10,000. At or above that boundary, Squoosh counts distinct succeeded objects it actually reads, up to 20 pages of 100 objects, and marks the count partial and truncated. It does not report the unreliable total as an exact count. Reordered Search pages can still omit records even after duplicate IDs are removed.
  • List fallback: Search is unavailable for businesses in India. A non-authentication Search 4xx response normally falls back to the List API. Rejected API versions fail closed. List has no status filter, so its 20-page limit includes incomplete payments as well as succeeded ones. The count is marked truncated only when the last permitted page still reports more records.
  • Rate and permission failures: authentication, permission, and 429 errors are surfaced directly. No automatic local retry loop runs. The connector declares a minimum refresh interval of 15 minutes. It is not enrolled in unattended snapshot refresh at the auth stage.
  • Sandbox totals: test-mode objects are separate from live payments. Stripe documents that list-all requests can omit objects generated by test clocks.
  • Account scope: the key selects the Stripe account. This connector does not aggregate connected accounts or separate a multi-store account into individual stores.

The Search query uses both documented numeric creation-time comparisons. Stripe's guide does not show a same-field double-bound example; List with explicit creation bounds is the fallback if Search rejects the query. See Stripe Search, Search pagination, and PaymentIntent status verification.

Troubleshooting

Problem What to do
Publishable key rejected Create a restricted key. pk_ keys cannot read payments.
Invalid or expired key Check the selected Stripe account and mode. Rotate or replace the key in Stripe, then reconnect in Squoosh.
Missing PaymentIntents Read permission Edit the restricted key's permissions in Stripe. Search permission coverage still requires sandbox validation for this beta.
Connected account has zero payments Confirm the mode and the full UTC creation-time window. Zero is valid data, not an authentication failure.
Count differs from the dashboard Compare succeeded PaymentIntents using creation dates and the same UTC bounds. Check renewals, refunds, legacy payments, index lag, and truncation warnings.
Search unavailable Squoosh uses the bounded List fallback when eligible. India accounts cannot use Search.
Rate limit or temporary provider error Retry later. A 429 is retryable even when it has no rate-limit-reason header.
Invalid API version or malformed response Contact Squoosh support. These failures need connector investigation; repeatedly replacing a valid key will not resolve them. Include the failure status, never your API key.
No conversion rate or shopper calibration appears This beta reads a payment count only. It does not yet change AI shopper behavior.
Snowflake Connect a CSV / Excel import