Stripe key and sales tax

Your shop talks to Stripe with a key. The key must be allowed to do each job the shop does. This page lists those jobs and shows you how to allow them. It ends with sales tax, which you also set up in Stripe.

A key made for an older version of the shop may lack a few of them. The Settings tab tells you which. See Check that it worked.

Which key to use

Stripe has two kinds of key that can charge cards.

• A secret key starts with sk_live_ or sk_test_. It can do anything in your Stripe account, so it works with no setup. It is also the worst key to lose.
• A restricted key starts with rk_live_ or rk_test_. It can only do the jobs you allow. Stripe tells you to use this kind, and so do we.

A restricted key needs the permissions in the table below. Read why on Connect Stripe.

The permissions

Each permission is a row in Stripe. Set each row below to Read or Write, as shown. Leave every other row at None. Write lets the key read the row too.

Row in Stripe	Set it to	What your shop uses it for
Payment Intents	Write	Takes the card payment at checkout.
Setup Intents	Write	Saves a card for a plan, so later bills can be paid.
Customer Sessions	Write	Shows a buyer their saved cards at checkout.
Customers	Write	Keeps a record of each buyer in Stripe.
Products	Write	Copies the things you sell into Stripe.
Prices	Write	Copies their prices into Stripe.
Tax Calculations	Write	Works out the sales tax on an order.
Tax Transactions	Write	Records the tax on each sale and each refund.
Payment Method Domains	Write	Turns on Apple Pay, Google Pay and Link for your web address.
Webhook Endpoints	Write	Sets up and fixes the webhook, the message Stripe sends when someone pays.
Refunds	Write	Gives money back when you refund an order.
Subscriptions	Write	Starts, changes and ends plans.
Invoices	Write	Bills each plan when it renews.
Coupons	Write	Turns your discount codes into money off a plan.
Customer Balance Transactions	Write	Pays referral rewards as credit on a bill.
Confirmation Tokens	Read	Reads the card details a buyer typed, to finish the payment.
Payment Methods	Read	Reads a saved card, such as its last four digits.
Tax Settings	Read	Reads whether your prices include tax.
Tax Registrations	Read	Reads which states you collect tax in.
Credit Notes	Read	Takes credit notes off your sales in the sales tax report.
Checkout Sessions	Read	Finishes orders started on the older checkout.

That is fifteen rows at Write and six at Read.

Stripe may not show Tax Transactions as a row of its own. It can sit under Tax Calculations. If you cannot find it, setting Tax Calculations to Write is enough.

Stripe groups the rows under headings, and may spell a name a little differently. If you cannot find one, type it into Stripe’s search box.

An older key may also have Promotion Codes, or Write on Checkout Sessions. That does no harm. The shop no longer needs them.

Give your key the permissions

Stripe cannot add a permission to a key by itself. You set them by hand, in Stripe, under Developers, then API keys. Stripe’s guide to restricted keys has more detail.

You can edit the key you have, or make a new one.

Edit the key you have

1. In Stripe, go to Developers, then API keys.
2. Find your key under restricted keys. Click the three dots at the end of its row.
3. Click Edit key.
4. Set each row as in the table above.
5. Save your changes.

The key itself stays the same, so there is nothing to paste into your website.

Or make a new key

1. In Stripe, go to Developers, then API keys.
2. Click Create restricted key. If Stripe offers a ready-made set of permissions, skip it and start from none.
3. Type a name in Key name, such as Website.
4. Set each row as in the table above.
5. Click Create key. Stripe sends you a code to prove it is you.
6. Copy the key. It starts with rk_. Stripe shows it only once.

7. In your website, go to Plugins, then Commerce. Click the Settings tab, then Stripe keys →.
8. Paste the new key over the dots in Stripe secret key.
9. Click Save Settings.

Check that it worked

1. Go to Plugins, then Commerce.
2. Click the Settings tab.
3. Near the top, click View Stripe connection information to open it.
4. Read the lines inside.

When something is wrong, the folded line ends in needs attention, so you see it without opening it.

Each time the tab opens, your website tests the key for every permission in the table. One of these shows.

You see	What it means
Stripe key: has every permission this store needs.	You are done.
A box titled Your Stripe key is missing permissions this store needs	It names each one that is missing, with Stripe’s own message. Add those in Stripe, then open the tab again.
A box titled Stripe does not accept this key	The key is wrong, or it was rolled or deleted in Stripe. Paste a key that works.
Stripe key: not checked	The test could not run, for example before a key is saved. It is not an error.

Stripe’s message may name a permission its own way. The name in bold beside it matches a row in the table above.

Two jobs it does for you

Opening the tab also does two jobs. You do not click anything.

• It fixes the webhook. If a new version of the shop needs a webhook event yours does not send, the event is added. A shop with no webhook at all still needs the button in Connect Stripe, step 5.
• It turns on Apple Pay, Google Pay and Link. Your web address is added to Stripe for them, with and without www. in front. A line starting with Apple Pay, Google Pay and Link: registered for shows it worked.

Your website also does both once a day. When it changes something, it tells you through Notifications.

Sales tax (US only)

Your shop adds sales tax only on orders to a US address. It adds it only in states where you have an active registration in Stripe Tax. Everywhere else, the tax on an order is zero.

A registration is a state’s OK for you to collect its sales tax. You get it from the state. Then you add it to Stripe, so Stripe knows to charge tax there.

Set it up

1. In Stripe, set up Stripe Tax. It asks for your head office address and what you sell. Stripe’s guide to setting up Stripe Tax walks through it.
2. Add your home state’s registration. In Stripe, go to Tax, then Locations. Click Add registration, pick your state, and choose I’ve already registered. Stripe’s guide to adding a registration has each step.

Skip step 2 if your home state has no sales tax. Delaware, Montana, New Hampshire and Oregon have none.

3. In your website, go to Plugins, then Commerce, and click the Settings tab. The Store tab opens.
4. In the Store box, turn on Calculate tax with Stripe Tax.
5. Click Save.

Open View Stripe connection information, near the top of the tab. A line starts with Stripe Tax registrations:. It lists the states you are registered in, with your home state marked (head office). A warning box shows if tax is on but no state will be taxed. Its Stripe Tax registrations → link opens the page in Stripe where you fix it.

Watch for new states

Stripe keeps an eye on your sales into every other state. Each state has a threshold, an amount of sales into that state. Pass it, and the state may want you to collect its tax. When you pass one, Stripe tells you.

• Your website shows the same picture for every state, under Reports, then Sales tax. See Reports and the dashboard.
• In Stripe, go to Tax, then Locations, and open the Needs attention tab. The See what needs attention → link, inside View Stripe connection information, goes straight there.
• Stripe also emails the account owner. It only does this once your sales for the year before reach $10,000. Below that, check the tab yourself now and then.
• Stripe does not watch your home state. That is why you add it by hand, in step 2 above.

Passing a threshold changes nothing at checkout on its own. To start collecting in a new state:

1. Register with that state first. Never collect a state’s tax before you are registered there. Stripe can register for you in states other than your home state. See Stripe’s guide to registering.
2. Add the registration in Stripe, under Tax, then Locations, as in step 2 above.

Within ten minutes, checkout adds tax for buyers in that state. Stripe’s guide to monitoring explains how the thresholds are counted.

If you moved here from another platform this year

Stripe only counts sales it took itself, plus sales you import. Sales from your old shop do not count. So you might pass a threshold without Stripe knowing.

The fix is to import your earlier sales into Stripe Tax. Stripe takes them as a CSV file, which is a spreadsheet saved in a plain format. Your bookkeeper may want to do this part.

1. Export your past orders from your old platform.
2. Lay them out the way Stripe asks: one row for each item sold, with Stripe’s own column names. Stripe’s guide to importing transactions lists every column and has a sample file.
3. In Stripe, go to Tax. Click Quick actions, then Import transactions.

4. Click Import CSV. Pick your file, then click Import File.
5. Watch the status in the panel that opens. If any rows fail, Stripe lets you download a list of them, with the reason for each.

Once imported, those sales count toward each state’s threshold.