# Outfitter

Source: https://developers.swell.is/app-guides/outfitter

Outfitter is a storefront app for selling merch, such as tees, hoodies, caps, mugs and totes. It renders the whole storefront itself, without a theme, and comes with a visual editor. You build the home, product and category pages from sections, edit the store's copy on the page itself, and set your logo and colors in its settings. Checkout hands off to Swell's hosted checkout.

## How it works

| When | What the app does |
| --- | --- |
| You create a storefront with Outfitter | Sets up the storefront with Outfitter's default pages, copy and colors. Customers see it at your store's address once you publish it. |
| A shopper opens a page | Renders the page from your sections, copy and settings, with products, prices and stock from your catalog. Home, product and category pages are served from the edge cache and refreshed in the background. |
| You edit the store in the editor | Saves section and copy changes as you make them. Settings are saved when you click Save. Shoppers see a change once their cached page refreshes. |
| A shopper adds a product to the cart | Checks that required options are answered, then adds the item with its options. Option prices are added to the item's price. |
| A shopper checks out | Shows the items, shipping options and total for review, then sends the shopper to Swell's hosted checkout to pay. |
| A shipment is recorded on an order | Shows its carrier and tracking number in the shopper's order history. |

## Before you begin

- At least one product and one category. The editor previews the product and category pages with the first of each.
- Shipping set up in Swell, or a fulfillment app that provides shipping rates. Outfitter shows the rates your store returns.
- Payment methods set up in Swell. Swell's hosted checkout takes the payment.

## Set up

Set up Outfitter in your test environment first, and place a test order there before you go live.

**1. Install Outfitter**

Install Outfitter from the Swell App Store. Installing adds the app to your store, but not a storefront.

**2. Create a storefront**

In Swell, go to **Online Store > Storefront**, click **Add storefront** and choose **Browse catalog**. Under **My library**, click **Create storefront** on Outfitter. When the page says your storefront is ready, it is listed in **Online Store > Storefront**.

**3. Open the editor**

In **Online Store > Storefront**, click **Open editor** on the storefront. The editor opens in a new tab.

**4. Set your name, logo and colors**

In the editor, click **Settings**. On **General**, enter the store name and upload your logo. On **Colors**, set the seven colors. Then click **Save**.

**5. Build your pages**

Under **Pages**, choose **Home**. Add sections with **+ Add section**, drag rows to reorder them, and click any line in the preview to change its copy. Then do the same for **Product** and **Category**.

**6. Place a test order**

In **Online Store > Storefront**, open the storefront's ⋮ menu and choose **Preview**. Add a product to the cart and check out. **Continue to payment** takes you to Swell's hosted checkout to place the order, and the order then appears in **Orders**.

**7. Go live**

Apps and storefronts are separate in the test and live environments, and sections, copy and settings don't carry over. In the live environment, repeat steps 1 to 5. Then in **Online Store > Storefront**, open the storefront's ⋮ menu and choose **Publish**. Publishing makes it the storefront customers see at your store's address and on your custom domains.

If you turned on **Demo store**, turn it off before you take real orders.

## Using Outfitter

### Pages and sections

The home, product and category pages are each built from a list of sections. In the editor, choose a page under **Pages**. Then:

- To add a section, click **+ Add section** and choose a type. A page holds up to 20 sections.
- To reorder sections, drag a row by its handle, or press Alt + ↑ or Alt + ↓ with the row focused. In the preview, you can also drag a section by its corner label.
- To change a section's copy, images and appearance, click its row, or a blank part of it in the preview, to open **Section settings**.
- To hide a section without deleting it, click its eye. A hidden section stays in the list until you show it again.
- To delete a section, click its ×. The editor asks before deleting it.
- To check other screen sizes, switch the preview between **Desktop**, **Tablet** and **Mobile**.

The product page has one list of sections, shown on every product, and the category page has one list, shown on every category. The editor previews them with a sample product and category. Each of these pages keeps a required section, **Product detail** or **Category products**, which you can move but not hide or delete.

If the home page has no sections, it shows a standard hero and product grid. If every section on it is hidden, shoppers see nothing between the header and the footer.

### Section types

Every section type can go on any of the three pages, in any number.

| Section | What it shows |
| --- | --- |
| Hero | An eyebrow, a large heading and a line beneath, with an optional background image. |
| Text | A heading and a paragraph. |
| Image and text | A picture beside a heading and a paragraph, on either side. |
| Call to action | A heading with one button. |
| Products | A grid of products, either the newest or one category's, with an optional row of category links. |
| Announcement bar | One line in a slim strip, such as a shipping threshold or a drop date, with an optional link. |
| Long text | Several paragraphs beside a heading. |
| Features | Up to four short points side by side, each a title and a line. |
| Steps | A numbered how-it-works in three steps. |
| Stats | Up to four large figures, each with a label. |
| Testimonials | Up to three customer quotes, each with who said it. |
| FAQ | Up to four questions and their answers. |
| Logo strip | A line and up to four names or logos. |
| Image banner | A wide picture with a heading, a line and a button over it. |
| Categories | Your categories as tiles, each linking to its page. |
| Product spotlight | One product, large, beside your copy and a button. |
| Product row | A short row of products, either the newest or one category's, with a link to see all. |

### Editing copy

Every heading, label, button and message the store shows can be edited, 143 strings in all, from the header and footer to the cart drawer. To change one, click it in the preview and type. You can also edit a section's copy in **Section settings**. Product names, prices and descriptions come from your catalog, so edit them in Swell.

The cart, checkout, account and not-found pages have no sections. Choose them under **Pages** to edit their copy the same way.

Copy is saved for each language. If your store sells in more than one, switch the language in the preview's header, then edit the copy for that language. A string with no translation shows the copy for your store's default language.

In the dashboard, the storefront's **Settings** tab has the same copy in its **Content** panel, grouped by page.

### Branding

The store name shows in the header and page titles, and a logo replaces the name in the header. Seven colors are used across the whole store, from buttons to the lines between rows. To change them in the editor, click **Settings**: the store name and logo are on **General** and the colors are on **Colors**. Click **Save** to apply them. See Settings below for each one.

### Product options

The product page shows every active option on the product:

- Variant options, such as size and color, choose the variant. Swell matches the chosen values to a variant when the item is added to the cart.
- If the values of an option have images, choosing a value shows its image as the main product photo. To show each colorway, add an image to each value of the color option.
- Options that aren't variant options, such as a gift note or a woven label, can be dropdowns, checkboxes or text fields. Each can have a price, which is added to the item and carries through to the cart and the order.
- Required options must be answered before the product can be added to the cart.
- An option that depends on another option is shown only when the shopper chooses one of the values it depends on.

The product page also shows up to four images, the sale price when the product is on sale, and up to four of the product's up-sells. A product that is out of stock and can't be backordered shows **Out of stock** instead of **Add to cart**.

### Checkout and fulfillment

The checkout page is a review step. It lists the items, the shipping options and the total, and **Continue to payment** takes the shopper to Swell's hosted checkout to enter their address and pay. Outfitter never handles payment.

Shipping options come from your store, whichever carrier or app provides them, and appear once the shopper has entered a delivery address. When a shipment is recorded on an order, its carrier and tracking number show in the shopper's order history. Any fulfillment app that records shipments works with Outfitter. [Printful](https://developers.swell.is/app-guides/printful) suits print-on-demand merch, but Outfitter doesn't need it.

### Accounts, languages and currencies

Shoppers can sign up, sign in, reset their password and see their 20 most recent orders. If your store sells in more than one language or currency, the header has a menu for each, listing the ones your store is set up for.

### Demo mode

With **Demo store** on, the footer of every page and every product page show a notice that the store is a demo and orders aren't fulfilled. Use it to show the store to your team before it takes real orders. Demo mode doesn't stop orders from being placed.

### In the dashboard

| Where | What it's for |
| --- | --- |
| Online Store > Storefront | Create a storefront with Outfitter, open the editor with Open editor, and preview or publish a storefront from its ⋮ menu. |
| The storefront's Settings tab | The Outfitter, Content and Sections panels: the settings, the store's copy and the home page's sections. Click Save changes to save them. |
| Apps > Outfitter | The app page, which lists the storefronts that use Outfitter. Uninstall the app from here. |

## Settings

Settings are in the editor under **Settings**, and in the **Outfitter** panel on the storefront's **Settings** tab in the dashboard. Each storefront has its own settings.

| Setting | Description | Default |
| --- | --- | --- |
| Store name | Shown in the header and page titles. | The store name in Settings > General |
| Logo | Replaces the store name in the header. A transparent PNG works best. | None |
| Primary | Buttons, active links and focus outlines. | #F0F0F0 |
| Secondary (on primary) | Button labels and inverted sections, shown on Primary. Keep it high contrast. | #0F0F0F |
| Text | Headings and body copy. | #F0F0F0 |
| Muted text | Prices, captions and product details. | #9E9E9E |
| Background | The page behind everything. | #0F0F0F |
| Surface | Product image backdrops and quiet blocks. | #181818 |
| Border | Lines between rows. Input edges are drawn a step stronger. | #3F3F3F |
| Page cache (seconds) | How long a page is served from the edge cache before it's refreshed in the background. 0 turns caching off. The most is 86400, one day. | 60 |
| Demo store | Shows a notice in the footer and on every product that orders aren't fulfilled. | Off |

## Limitations

- Outfitter has a home page, product and category pages, a cart, a checkout review page and account pages. You can't add pages of your own.
- A page holds up to 20 sections. The product and category pages each have one list of sections, shared by every product or category.
- A category page shows up to 24 products, on one page.
- The product page shows up to four images.
- There's no product search.
- Order history shows a shopper's 20 most recent orders.
- The editor uploads PNG, JPEG, GIF and WebP images up to 5 MB. To use an SVG, paste its URL into the image field.
- Changes reach shoppers as cached pages refresh, usually within the page cache time.
- Demo mode shows notices but doesn't stop orders.

## Troubleshooting

### Opening /editor shows the home page

The editor only opens from the dashboard, for a signed-in admin of the store. Go to **Online Store > Storefront** and click **Open editor** on the storefront.

### A change doesn't show on the storefront

Pages are served from the cache for the **Page cache** time, 60 seconds by default. Wait for the page to refresh, or set **Page cache** to 0 while you build the store and set it back before you go live.

### Product or Category is missing from the editor's pages

The editor previews these pages with your first product and category. Add a product or a category, then reopen the editor.

### The home page shows a hero and product grid you didn't add

The home page has no sections, so it shows the standard hero and product grid. Add a section to replace them.

### The home page is empty between the header and footer

Every section on it is hidden. Show a section, or delete them all to get the standard hero and product grid back.

### "That could not be added to your cart."

Swell couldn't match the chosen values to a variant, or a chosen value no longer exists. Check that the product has a variant for each combination of its variant options.

### Choosing a color doesn't change the photo

Add an image to each value of the color option. Only an option whose values have images changes the photo.

### The checkout page shows no shipping options

Shipping options appear once the shopper has entered a delivery address, which happens on Swell's hosted checkout. If none appear there either, check your shipping settings in Swell.

### "The store's languages could not be read"

The editor couldn't read your store's languages, so it doesn't save copy changes. Reopen the editor.

## Uninstalling

You can't uninstall Outfitter while a storefront uses it. If the Outfitter storefront is your published one, publish another storefront first. Then in **Online Store > Storefront**, open the Outfitter storefront's ⋮ menu and choose **Delete storefront**. Its sections, copy and settings are deleted with it.

Then go to **Apps > Outfitter** and choose **Uninstall app**. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately. Your products, customers and orders aren't affected.

## For developers

Outfitter is an Astro app that runs on Cloudflare Workers behind the Swell proxy. It reads the catalog, cart and account through the Swell storefront API.

Sections, copy and settings for a storefront live in one document, `/:storefronts/{id}/configs/settings`:

- `values.outfitter`: the settings in the table above.
- `values.content`: copy for the store's default language by string id, and translations under `$locale.<code>`.
- `values.sections`: the section lists, under `home`, `product` and `category`. Only `home` is a dashboard field.

The app asks for these permissions:

- `write_:storefronts`: saves sections, copy and settings to the storefront.
- `write_:files` and `write_files`: upload images from the editor.

The editor at `/editor` and its API under `/editor/api/` only answer requests that come through the dashboard from a signed-in admin of the store. Other requests to `/editor` are redirected to the home page, and the API answers 404.

Home, product and category pages are cached at the edge and refreshed in the background. The cache key covers the storefront, language, currency, and the shopper's account and cart. Cart, checkout, account and editor pages are never cached.

## Support

Swell builds and maintains the Outfitter app. For help with it, email support@swell.is.