# Stripe key and sales tax

Give your Stripe key the permissions your shop needs, check that it worked, and set up US sales tax.

Source: https://docs.lookoutridgeit.com/commerce/stripe-key-and-tax/

**Add-on**
Commerce is an add-on, so not every website has it. If it is not in
your menu, see [Add-ons](https://docs.lookoutridgeit.com/billing/add-ons/) to add it.

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](https://docs.lookoutridgeit.com/commerce/stripe-key-and-tax/#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](https://docs.lookoutridgeit.com/commerce/connect-stripe/#step-3-make-a-restricted-key).

## 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](https://docs.stripe.com/keys/restricted-api-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.

**Warning**
The next step changes your live shop right away. If the key is wrong,
checkout stops until you fix it.

Use a key from the same mode as your publishable key. A `pk_live_` key needs
an `rk_live_` key, and a `pk_test_` key needs an `rk_test_` key.

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](https://docs.lookoutridgeit.com/commerce/connect-stripe/#step-5-create-the-webhook).
- **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](https://docs.lookoutridgeit.com/plugins/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.

**Important**
Where you owe tax is a question for your accountant. This page shows where the
switches are. It cannot tell you which ones to flip.

### 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](https://docs.stripe.com/tax/set-up) 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](https://docs.stripe.com/tax/registering#add-a-registration)
   has each step.

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

**Warning**
The next step changes what buyers pay, right away. From the next order, US
buyers in your registered states pay tax.

If your shop has already sold something, contact us before you do it.

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](https://docs.lookoutridgeit.com/commerce/reports/#sales-tax).
- 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](https://docs.stripe.com/tax/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](https://docs.stripe.com/tax/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](https://docs.stripe.com/tax/imports) lists every
   column and has a sample file.
3. In Stripe, go to **Tax**. Click **Quick actions**, then
   **Import transactions**.

**Warning**
An import cannot be deleted. Check the file before you upload it. To cancel a
row later, you import a second row that voids it.

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.

**Contact support**
Contact us if:

- the **Settings** tab still says permissions are missing after you added them
  in Stripe
- it says **Stripe does not accept this key**, and you pasted a fresh one
- tax shows up in a state you did not expect, or not in one you did

Send us the last four letters of a key if you need to, never the whole thing.

Email [support@lookoutridgeit.com](mailto:support@lookoutridgeit.com).
[Getting support](https://docs.lookoutridgeit.com/help/getting-support/) says what to put in the message.