> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartwpplugins.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings reference

> Every setting at every level, its key, its default, and which tier honours it

Settings live at three levels. A preset-level setting overrides the store-wide one. An item-level setting applies to one line.

All store settings live in a single option, `cartpresets_settings`. Preset and item settings live in their own tables.

🖼️

Screenshot pending

The Settings screen with the sidebar System status card visible

## Store settings

The sections below are in the order the screen draws them: LicencePro, Cart behaviour, Usage limitsPro, Carrier productPro, Messages and labels, Link settings, Menu location, Data management.

The free version draws every card too. The Pro-only ones carry a **Pro** tag, and their controls are locked.

Most of the screen saves together with **Save changes** at the bottom. The licence buttons, the carrier product buttons, and export and import act straight away instead, so they never touch the save bar.

### LicencePro

The first card on Settings is **Licence**. On Pro it holds the key, its status, and the **Activate**, **Sync now** and **Deactivate on this site** buttons. Only an administrator sees the buttons; anyone else who can open Settings sees the card read-only. The free version has no Licence card, so Settings starts with Cart behaviour. The licence has no stored setting keys in `cartpresets_settings`. See [Licence and updates](https://docs.smartwpplugins.com/cartpresets/licence.md).

### Cart behaviour

Four blocks, in this order: what happens to the cart a link finds, what happens when an item can't be added, where a customer lands when the link works, and where they land when it can't be used at all.

**Existing cart**

| Setting | Key | Default | Tier |
| - | - | - | - |
| Clear the existing cart | `clear_cart` | Off | Both |
| Allow duplicate presets | `allow_duplicate` | Off | Both |
| Keep existing items | `keep_existing` | On | Both |

The lower two are disabled while **Clear the existing cart** is on. An emptied cart has no earlier copy to keep and nothing of the customer's to spare.

**Unavailable items**

| Setting | Key | Default | Tier |
| - | - | - | - |
| Unavailable items | `invalid_item` | `skip` | Both |

`invalid_item` accepts `skip` (**Skip the item**) or `none` (**Refuse the preset**).

**Redirect after adding**

| Setting | Key | Default | Tier |
| - | - | - | - |
| Redirect after adding | `post_add` | `cart` | Both |
| Custom URL | `post_add_url` | Empty | Both |

`post_add` accepts `cart`, `checkout`, `stay` or `custom`. A `custom` destination won't save without an address.

**Unavailable links**

| Setting | Key | Default | Tier |
| - | - | - | - |
| Unavailable links | `refused_action` | `cart` | Both |
| Custom URL | `refused_url` | Empty | Both |
| Show an error message | `refused_notice` | On | Both |

`refused_action` accepts `cart` (**Cart**) or `custom` (**Custom URL**). Choosing **Custom URL** shows a **Custom URL** field, and a custom destination won't save without an address. One answer covers every way a link can be refused: expired, sold out, switched off, restricted, used up, or matching no preset at all. See [Where customers land](https://docs.smartwpplugins.com/cartpresets/links/destinations.md).

> [!NOTE]
>
> This is store-wide and editable in both versions. Only the per-preset override needs Pro. Where a refused customer lands can't put a link back on sale, so there's no reason to lock it.

### Usage limitsPro

| Setting | Key | Default | Tier |
| - | - | - | - |
| Count orders with these statuses | `redemption_statuses` | On hold, Processing, Completed | Pro to edit, honoured on both |

A slot is taken when an order enters one of these, and given back when it leaves them, so a cancelled order doesn't permanently eat part of a limited run. Clearing every box falls back to the default. On the free version the boxes are locked and the stored set still applies. See [Purchase limits](https://docs.smartwpplugins.com/cartpresets/building/purchase-limits.md).

### Carrier productPro

| Setting | Key | Default | Tier |
| - | - | - | - |
| Carrier product | `carrier_product_id` | `0` (none) | Pro to change |

The hidden product custom items ride on. With none linked, the card shows an empty slot with **Create carrier product** and **Choose a product**. On the free version the card is locked. See [The carrier product](https://docs.smartwpplugins.com/cartpresets/settings/carrier-product.md).

### Messages and labels

| Setting | Key | Default | Tier |
| - | - | - | - |
| All twenty-one strings | `notices` | Empty (shipped wording) | Both |

Twenty-one strings, drawn as twenty-two editable fields: the per-customer cap message has a singular and a plural form. They sit in four groups, each opened with **Edit wording**, and a search box finds a message by its wording or by when it shows. Only the ones you've rewritten are stored. See [Cart notices and wording](https://docs.smartwpplugins.com/cartpresets/links/wording.md).

### Link settings

| Setting | Key | Default | Tier |
| - | - | - | - |
| URL parameter | `url_param` | `preset` | Both |
| Pretty permalink base | `permalink_base` | `/preset/` | Both |
| Append the preset name as a UTM campaign | `utm` | Off | Both |

Changing either URL setting breaks links you've already shared. A read-only **Link preview** shows how every preset link will read.

### Menu location

| Setting | Key | Default | Tier |
| - | - | - | - |
| Menu location | `menu_location` | `own` | Both |

`own` (**Top-level menu**) is a **Cart Presets** menu with All Presets, Add New Preset and Settings beneath it. `products` (**Under Products**) is a single **Cart Presets** entry under **Products**, with no submenu. Add New and Settings stay reachable from the listing screen. Saving this reloads the page to move the menu.

### Data management

| Setting | Key | Default | Tier |
| - | - | - | - |
| Presets and their settings | `delete_links` | Off | Both |
| Store settings, wording and licence (on free: Store settings and wording) | `delete_settings` | Off | Both |
| The carrier product | `delete_carrier` | Off | Both |

These three boxes sit under **Delete on uninstall**, and they're editable on both versions. Everything is kept unless you tick it. Whatever you tick is permanently deleted on uninstall. Deactivating never removes anything. `delete_settings` covers more than its wording says: the whole settings option, your licence record, each administrator's listing preferences, and cached preset data.

Above them, **Preset data** holds **Export presets** and **Import presets**Pro. They act straight away, and they're locked on the free version. See [Import and export](https://docs.smartwpplugins.com/cartpresets/import-export.md).

See [Data and uninstall](https://docs.smartwpplugins.com/cartpresets/settings/data-and-uninstall.md) and [Privacy and personal data](https://docs.smartwpplugins.com/cartpresets/settings/privacy.md).

## Preset settings

Set in the editor, on one preset.

| Setting | Key | Default | Tier |
| - | - | - | - |
| Starts on | `created_at` | Now | Pro to edit |
| Preset ends on | `end_at` | Empty | Pro to edit |
| Maximum orders | `max_total` | Empty | Pro to edit, honoured on both |
| Maximum orders per customer | `max_per` | `0` | Pro to edit, honoured on both |
| Redirect after adding | `redirect` | `global` | Both |
| Custom URL | `custom_url` | Empty | Both |
| Existing cart: **Store default** / **Override** | `cart_override` | Off (**Store default**) | Both |
| Clear the existing cart | `clear_cart` | Off | Both |
| Allow duplicate presets | `allow_duplicate` | Off | Both |
| Keep existing items | `keep_existing` | On | Both |
| Coupon code | `coupon` | Empty | Pro (not applied on free) |
| Signed-in customers only | `logged_in` | Off | Pro (not enforced on free) |
| Allowed roles | `roles` | Empty | Pro (not enforced on free) |
| Unavailable links | `refused_action` | `global` | Pro to edit, honoured on both |
| Custom URL | `refused_url` | Empty | Pro to edit, honoured on both |
| Show an error message (no editor control) | `refused_notice` | On | Pro to edit, honoured on both |

In the editor, each of **Existing cart**, **Redirect after adding** and **Unavailable links** has a **Store default** / **Override** switch. `redirect` and `refused_action` both store **Store default** as `global`. `refused_action` otherwise accepts `cart` or `custom`, the same two the store offers.

The editor has no switch for `refused_notice`. A preset that overrides **Unavailable links** keeps the stored value, which is on unless an import or the REST API set it off.

The three cart switches are only read while `cart_override` is on. On **Store default** the editor hides them and names the store's answer instead. See [Cart behaviour](https://docs.smartwpplugins.com/cartpresets/links/cart-behaviour.md#per-preset-override).

A role list implies the sign-in switch, because a guest holds no roles. Roles without `logged_in` would refuse every visitor while the editor showed no sign-in requirement. So saving a role list turns `logged_in` on, whether it arrives from the editor, an import or a filter.

> [!NOTE]
>
> There's no per-preset rejection message. A visitor who is turned away reads the store-wide wording: `not_signed_in` and `role_not_allowed` in **Messages and labels**.

## Item settings

Set on one item inside a preset.

| Setting | Key | Default | Tier |
| - | - | - | - |
| Discount type | `disc_type` | None | Both |
| Discount value | `disc_value` | `0` | Both |
| Use the regular price instead of the sale price | `use_regular` | Off | Both |
| Discounted payments | `sub_payments` | `0` (every payment) | Pro (free discounts every payment) |
| Waive the sign-up fee | `sub_waive_fee` | Off | Pro (free charges the fee) |
| Allow coupon discounts on this item | `allow_coupons` | Off | Both |
| Let the customer change the quantity in the cart | `allow_qty` | Off | Both |
| Minimum (quantity) | `qty_min` | `1` | Both |
| Maximum (quantity) | `qty_max` | `0` (no maximum) | Both |
| Customer can remove this item | `removable` | Off | Both |
| Variation attributes | `variation_attributes` | Empty | Both |
| Name (custom item) | `custom_name` | Empty | Pro |
| Custom price | `custom_price` | `0` | Pro |
| Description | `description` | Empty | Pro |
| Image | `image_id` | `0` | Pro |
| This item needs shipping | `requires_shipping` | Off | Pro |
| Weight, length, width, height | `weight`, `length`, `width`, `height` | Empty | Pro |
| Shipping class | `shipping_class_id` | `0` | Pro |

`disc_type` accepts `none`, `pct`, `fixed` or `custom`.

## What "Pro to edit, honoured on both" means

Some settings can only be *set* on Pro, but are *enforced* in both versions.

Purchase limits are the clearest case. Setting a cap needs Pro. Both versions count claims against a cap and refuse a link once it fills, because moving to the free version must never put a sold-out link back on sale.

The same logic covers schedules, and a preset's own **Unavailable links** override: moving to the free version shouldn't send a customer somewhere other than where the merchant chose. The rule is to honour restrictions and drop enhancements.

## Where settings are stored

| Level | Storage |
| - | - |
| Store | One option, `cartpresets_settings` |
| Preset | Columns and a settings blob on `cartpresets_presets` |
| Item | A settings blob on `cartpresets_items` |

Writes walk the schema, not the request, so a key that isn't in the schema is never saved, no matter what a request contains. Developers can register their own keys. See [the hooks reference](https://docs.smartwpplugins.com/cartpresets/developers/hooks-reference.md#schema).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.