> For the complete documentation index, see [llms.txt](https://native-app-co.gitbook.io/stork-credit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://native-app-co.gitbook.io/stork-credit/getting-started/installation.md).

# Installation & setup

Install Stork Credit, review the permissions it asks for, and switch on the cart and checkout widgets.

## Install the app

1. Open **Stork Credit** on the Shopify App Store and click **Install**.
2. Review the permissions (below) and approve.
3. Stork Credit opens on the **Plans** page and asks you to choose a plan. The rest of the app stays closed until you've picked one — **Continue on Free** is a perfectly good answer and keeps you on the free plan indefinitely.
4. You land on the Stork Credit home page inside your Shopify admin, with the **Setup guide** at the top.

## The setup guide

The **Setup guide** is the first card on the home page after you install. It lists the steps that get a store issuing credit, and ticks each one off as you complete it:

| Step                                                  | Complete when                                                     |
| ----------------------------------------------------- | ----------------------------------------------------------------- |
| **Create your first automation**                      | Your store has at least one automation                            |
| **Show rewards on your storefront** (optional)        | The Stork Credit app embed is switched on in your published theme |
| **Import existing balances** (optional)               | You have run a CSV import                                         |
| **Build custom rewards with Shopify Flow** (optional) | A Flow workflow has issued credit through Stork Credit            |

Only the first step is required. The others are marked **Optional** and can be left for later or skipped altogether.

At the top of the guide, **What do you want to do first?** lets you tick what you came for. Your answer moves the most relevant steps to the top. It is optional — click **Skip** to leave it.

Click **Dismiss** to remove the guide from the home page at any time, whether or not the steps are complete. It stays dismissed. If you uninstall and later reinstall the app, the guide appears again.

## Permissions

| Permission                         | Why it is needed                                                         |
| ---------------------------------- | ------------------------------------------------------------------------ |
| Read customers                     | Find the customer to credit, and resolve segments for scheduled rules    |
| Write customers                    | Create a customer when an email address has no account yet               |
| Read orders                        | Read line items, discounts, and totals when an order-value rule runs     |
| Read products                      | Check whether an order's products are in a targeted collection           |
| Manage store credit transactions   | Issue the credit itself                                                  |
| Read store credit accounts         | Read balances for the Customers' Store Credit report and reminder emails |
| Manage metaobjects and definitions | Store your automation rules in your shop, so they survive app reinstalls |

## Turn on the storefront widgets

The widgets are optional — automations work whether or not they are visible. They exist to tell customers what an order will earn **before** they buy.

### Cart widget (theme block)

Open **Storefront widgets** in the app navigation. Each button opens the theme editor in a new tab with the change already made, so all you do is save.

1. Click **Turn on app embed**. The theme editor opens on **App embeds** with **Stork Credit** switched on. Click **Save**.
2. Click **Add to cart page**. The theme editor opens with the **Automatic Store Credit** block added to your cart page, showing a sample amount so you can see it.
3. Drag the block where you want it, and set the background, text, and accent colours to suit your theme.
4. Click **Save**.

{% hint style="warning" %}
The block shows nothing until the app embed is enabled — the embed is what tells the block the current cart contents and customer.
{% endhint %}

Prefer to do it by hand? In the Shopify admin go to **Online Store → Themes → Customize**, open your **Cart** page, choose **Add block → Apps → Automatic Store Credit**, then open **App embeds** in the left sidebar and enable **Stork Credit**. **Save**.

### Checkout widget

{% hint style="info" %}
The Checkout widget needs a store on **Shopify Plus** — Shopify only allows app blocks in checkout on that plan. On any other plan, skip this step. The Cart widget above works on every plan.
{% endhint %}

1. On the **Storefront widgets** page, click **Open checkout editor**, or go to **Settings → Checkout → Customize**.
2. **Add app block → Automatic Store Credit**.
3. Position it where you want and **Save**.

Full detail on both widgets, including when they stay hidden: [Cart & checkout widgets](/stork-credit/integrations/storefront-and-checkout.md).

## Pick a plan

You choose your plan the first time you open the app (see [Install the app](#install-the-app) above). The **Free** plan allows one active automation and 20 rows per CSV import — enough to test the app end to end.

Open **Plans** in the app navigation to move up or down at any time. See [Plans & billing](/stork-credit/reference/plans-and-billing.md).

## Verify it works

The fastest end-to-end check:

1. Create a rule that credits a small flat amount on every order — see the [Quickstart](/stork-credit/getting-started/quickstart.md).
2. Place a test order on your store **with a customer account attached**.
3. Mark the order as paid.
4. Open the automation's **Runs** tab. A run should appear within a few seconds.
5. Open that customer in the Shopify admin and confirm the store credit balance.

{% hint style="info" %}
Rules run when an order is **paid**, not when it is placed. An unpaid or pending order will not trigger anything.
{% endhint %}

## Uninstalling

Uninstalling stops all automations immediately. **Credit already issued stays with your customers** — it is native Shopify store credit and belongs to the customer accounts, not to the app.