Connecting to Stripe

A Stripe Connection lets reports read your Stripe data, such as invoices, customers, subscriptions, charges and payouts. Stripe macros only ever read, so nothing in your Stripe account is ever created, changed, refunded or cancelled.

Use a restricted key

Stripe has two kinds of key that can read data. Use a restricted key where you can.

Key begins	What it is
rk_live_ or rk_test_	A restricted key. It can be limited to reading only what your reports need, and deleted on its own at any time.
sk_live_ or sk_test_	Your account's secret key. It works, but it can also make changes in your account, such as issuing refunds.

A publishable key, beginning pk_, cannot read any data, so it is refused when you save the Connection.

Creating a restricted key

1. In the Stripe Dashboard, go to Developers, then API keys, and select Create restricted key.
2. Give the key a name you will recognise, such as Magic Suite reporting.
3. Set Read on each resource your reports use, such as Customers, Invoices, Subscriptions or Payouts. Leave everything else at None.
4. Create the key, and copy it.

Tip: if a report later fails with a 403 error, the key cannot read what the report asked for. Grant Read on that resource in Stripe, and run the report again.

Test mode and live mode

Stripe keeps test data and live data completely separate, each with its own keys. A key beginning rk_test_ or sk_test_ reads only test data, so a report using it shows none of your real payments. Use a key beginning rk_live_ or sk_live_ to report on real data.

Adding a Stripe Connection

1. In the Admin app, go to Connections and select Create.
2. Choose Stripe as the type. The URL is filled in for you: leave it as it is.
3. Leave User Name empty. Stripe uses the key alone.
4. Paste the key into API Key.
5. Leave Read Only ticked. It cannot be changed for a Stripe Connection, because Magic Suite only reads from Stripe.
6. Select Test Connection. A working key shows Connection Valid.
7. Save the Connection.

Macros

Macro	What it does
[Stripe.Connection:]	Sets the Stripe Connection used by the Stripe macros that follow it.
[Stripe.List:]	Lists objects of one type, optionally filtered with a query, with the properties you choose.
[Stripe.Property:]	Obtains one property of one object, given its Stripe ID.
[Stripe.Count:]	Counts the objects of one type, optionally filtered with a query.

Tip: rather than starting every report with a [Stripe.Connection:] macro, create a Macro Parameter Default for [Stripe.Connection:], with name set to the name of your usual Stripe Connection.

The type parameter takes one of: balance_transactions, charges, checkout_sessions, coupons, credit_notes, customers, disputes, events, invoice_items, invoices, payment_intents, payment_links, payouts, plans, prices, products, promotion_codes, refunds, setup_intents, subscription_items, subscriptions or tax_rates.

Examples

The open invoices, with the amount due on each:

[Stripe.List: type=invoices, query=status:'open', properties=id;customer_email;amount_due;currency, storeAsHidden=OpenInvoices, mode=Normal]

The number of active subscriptions:

[Stripe.Count: type=subscriptions, query=status:'active']

The twenty most recent payouts. Payouts cannot be searched, so this uses take rather than query:

[Stripe.List: type=payouts, take=20, properties=id;amount;arrival_date;status]

One property of one customer:

[Stripe.Property: type=customers, id=cus_ABC123, property=email]

Successful charges, with the whole customer object fetched so that its email address has a value:

[Stripe.List: type=charges, query=status:'succeeded', expand=customer, properties=id;amount;customer.email]

Choosing properties

• properties takes a semicolon-separated list, and can reach into nested values, such as customer.email. Leave it out of [Stripe.List:] to get every property.
• A property missing from some of the returned objects comes back empty for those objects.
• A property with no value on any of the returned objects fails the report, because that is usually a mistyped name.
• Stripe normally gives a related object, such as a charge's customer, as just its ID. Add expand to fetch the whole object: without expand=customer, customer.email has no value.
• A value containing square brackets must be in double quotes, or its closing bracket ends the macro early, for example properties="id;customer;items.data[0].price.id".

How many objects are returned

take sets the maximum number of objects. Without it, [Stripe.List:] returns at most 1,000, and [Stripe.Count:] stops counting at 1,000, so set take higher when you expect more.

Filtering with query

query uses Stripe's own search syntax, for example status:'active'. Only these types can be searched: charges, customers, invoices, payment_intents, prices, products and subscriptions.

Using query with any other type fails with an error. That is deliberate: for those types Stripe would ignore the query and return everything, which would look like a filtered result. Retrieve the objects instead, and filter them in the report.

Stripe's search results can lag slightly behind recent changes, so an object created moments ago may not be found yet.

Amounts

Stripe gives amounts in the currency's smallest unit, and Magic Suite does not convert them, so an amount of 1000 on a GBP charge is ten pounds. Some currencies, such as the Japanese yen, have no smaller unit, so divide by 100 only where you know the currency has one.

Troubleshooting

Message	What to do
That is a Stripe publishable key (when saving)	Use a restricted key (rk_) or a secret key (sk_) instead.
That is not a recognised Stripe API key (when saving)	Stripe API keys begin rk_test_, rk_live_, sk_test_ or sk_live_. A webhook signing secret, beginning whsec_, is not an API key.
Could not read the Stripe account (from Test Connection)	Check the key has not been revoked in Stripe, and that a restricted key can read what your reports need.
A report fails with 401 Unauthorized	The key has been revoked or replaced. Create a new key and update the Connection.
A report fails with 403 Forbidden	The restricted key cannot read that resource. Grant Read on it in Stripe.
Stripe is rate limiting this account	Request fewer objects, or run the report less often.
Stripe does not offer a search API for ...	That type cannot be searched. Remove query, and filter the objects in the report.
No value was found for ...	Check the property name. A nested value may need expand.
The report is empty, but Stripe has data	The Connection may hold a test mode key, beginning rk_test_ or sk_test_.
An amount looks a hundred times too large	Amounts are in the currency's smallest unit. See Amounts.

Not supported

• Writing to Stripe. There are no macros to charge, refund, cancel or create anything.
• Stripe Connect. A Connection reads only the account its key belongs to.
• Webhooks. Magic Suite reads from Stripe when a report runs, and does not receive events from Stripe. [Stripe.List:] with type=events can report on events instead.