> For the complete documentation index, see [llms.txt](https://help.pixfizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.pixfizz.com/personalization/custom-design-tools/business-card-tool-setup-and-activation/business-card-tool-configuration-reference.md).

# Business Card tool: configuration reference

Every setting the Business Card tool accepts, what it does, and what it defaults to. All of them are keyword arguments on the snippet call in `custom_script`.

***

### Overview

The tool reads its configuration from **one place**: the mount. That is the `custom_script` custom field on the `bc_artwork_front` template option.

It reads no product custom fields, no design custom fields and no site checklist. If you have any of those left over from an older install, they are doing nothing — see Settings that no longer do anything.

The mount looks like this:

```liquid
{% snippet 'product/business-card', bc_sides: '1' %}
```

Add arguments by comma-separating them:

```liquid
{% snippet 'product/business-card',
	bc_sides: '2',
	bc_trim_w: '85mm',
	bc_trim_h: '55mm',
	bc_units: 'mm',
	bc_placement: 'FILL' %}
```

**Why the mount and not a custom field.** `custom_script` is a field on the template option, and template options are included in a template export. A custom field is not: its definition has to be created on every object on every store before a value can even be stored, which is the slowest and most error-prone part of any install. Putting the settings in the mount means they travel with the template.

***

### The settings

There are 19. All are optional except `bc_sides`, and every default is already correct for a standard US business card.

#### Card geometry

| Argument    | Accepted values          | Default   | What it does                                                                                   |
| ----------- | ------------------------ | --------- | ---------------------------------------------------------------------------------------------- |
| `bc_sides`  | `1` or `2`               | `1`       | How many sides the customer supplies. Also accepts `single`, `double`, `duplex`, `two`, `both` |
| `bc_trim_w` | A length, e.g. `'3.5in'` | `3.5in`   | Finished card width, after cutting                                                             |
| `bc_trim_h` | A length, e.g. `'2in'`   | `2in`     | Finished card height, after cutting                                                            |
| `bc_bleed`  | A length                 | `0.125in` | Bleed on each edge. Artwork must reach this far; it is then cut off                            |
| `bc_safe`   | A length                 | `0.125in` | Safe zone inset. Text inside this line is guaranteed not to be cut                             |
| `bc_units`  | `in` or `mm`             | `in`      | **Display only** — see below                                                                   |

**Always write the unit.** `'3.5in'`, not `3.5`. A bare number is read in the store's display unit, so a bare `3.5` on a millimetre store makes the card three and a half millimetres wide. A value that carries its own unit always wins, whatever the store is set to.

**`bc_units` changes what the customer reads, not what the tool measures.** Everything inside the tool stays in inches — a PDF is measured in points and a photo in pixels over dpi, and neither becomes metric by relabelling it. What changes is the units shown on screen, and what a lab may type: with `bc_units: 'mm'` a bleed of `3` means 3 mm, while `0.125in` still means 0.125 inches.

#### Artwork rules

| Argument            | Accepted values   | Default | What it does                                                            |
| ------------------- | ----------------- | ------- | ----------------------------------------------------------------------- |
| `bc_min_dpi`        | A number          | `300`   | Below this the tool warns the customer their image may look soft        |
| `bc_max_mb`         | A number          | `100`   | Largest file the tool accepts, in MB                                    |
| `bc_block_on_error` | `true` or `false` | `false` | Whether an artwork error stops Add to Cart outright                     |
| `bc_human_check`    | `true` or `false` | `false` | Whether the tool tells the customer a person will check the artwork too |
| `bc_designer_link`  | `true` or `false` | `false` | Whether the tool offers a link to a designer                            |

`bc_block_on_error` is off by default on purpose. The tool already makes the customer tick an acknowledgement before they can continue when there is anything worth looking at, and that is usually the better trade — a hard block turns a soft problem into a lost order.

#### Output

| Argument        | Accepted values                       | Default          | What it does                                                                  |
| --------------- | ------------------------------------- | ---------------- | ----------------------------------------------------------------------------- |
| `bc_output`     | `NORMALISED` or `PASSTHROUGH`         | `NORMALISED`     | Whether the tool builds the print file or sends the customer's file unchanged |
| `bc_placement`  | `AUTO`, `FILL`, `FIT`, `TRIM`, `NONE` | `AUTO`           | How supplied artwork is placed on the card                                    |
| `bc_print_code` | A template option code                | `bc_print_front` | Which option the generated print file is written to                           |

**NORMALISED** builds a production PDF at the template's page size, whatever the customer uploaded. This is the default and the right choice for almost every store.

**PASSTHROUGH** attaches the customer's file unchanged. Use it only for labs whose customers reliably supply press-ready PDF/X and would rather receive exactly the file they sent. On PASSTHROUGH the customer cannot reposition their artwork, because there is no placement to move.

**How the placement modes behave:**

| Mode   | Behavior                                                                                           |
| ------ | -------------------------------------------------------------------------------------------------- |
| `AUTO` | Measures each file and picks one of the modes below. See the table underneath                      |
| `FILL` | Scales uniformly until the artwork covers the whole sheet, cropping whatever overhangs             |
| `FIT`  | Scales uniformly until the artwork sits wholly inside the sheet. Can leave bare stock at two edges |
| `TRIM` | Scales to the finished card size, then builds the bleed by mirroring the edges outward             |
| `NONE` | No scaling. Places the artwork at its true size, centred                                           |

**What `AUTO` decides:**

| The file                      | What AUTO does                              | Why                                                                         |
| ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
| Already at bleed size         | `NONE`                                      | It is already right; touching it would only degrade it                      |
| At finished size, no bleed    | `TRIM`                                      | Place it on the trim line and build the bleed for it                        |
| Right proportions, wrong size | `FILL`                                      | Scale it up or down; nothing is lost                                        |
| Proportions differ            | `FILL` on NORMALISED, `TRIM` on PASSTHROUGH | Something has to give, and on NORMALISED a crop beats bare stock at an edge |

`AUTO` is the right answer for a store selling to the public, because no single fixed mode suits every file: `FILL` crops a finished-size card by nearly its whole safe margin, and `TRIM` shrinks a file that already bleeds correctly.

This is the **on-drop** behavior only, not a lock. The customer can still move and resize the artwork afterwards unless `bc_reposition` is off.

#### What the customer sees

| Argument             | Accepted values        | Default | What it does                                                        |
| -------------------- | ---------------------- | ------- | ------------------------------------------------------------------- |
| `bc_show_bleed`      | `true` or `false`      | `true`  | Whether the proof opens with the bleed area shown                   |
| `bc_reposition`      | `true` or `false`      | `true`  | Whether the customer can drag and resize their artwork on the proof |
| `bc_preview`         | `true` or `false`      | `true`  | Whether the Artwork / Preview toggle and the 3D card are offered    |
| `bc_price_footer`    | `off`, `total`, `each` | `off`   | Whether the tool's footer shows a price, and as a total or per unit |
| `bc_requires_design` | `true` or `false`      | `true`  | Whether the product needs artwork before it can be ordered          |
| `bc_display`         | `modal` or `inline`    | `modal` | Whether the tool opens in a dialog or sits open in the page         |

`bc_reposition` has no effect on PASSTHROUGH — there is nothing to move, so the control never appears whatever this says.

`bc_display: 'inline'` renders the tool open and in flow, with no launch button and no dialog. Use it for a dedicated design page. The review step stays a dialog either way.

#### Which variant carries which choice

These do not set anything. They tell the tool which variant code to read on a store that named its variants differently.

| Argument          | Default      | Reads            |
| ----------------- | ------------ | ---------------- |
| `bc_sides_code`   | `bc_sides`   | The sides choice |
| `bc_shape_code`   | `bc_shape`   | The card shape   |
| `bc_corners_code` | `bc_corners` | The corner style |
| `bc_stock_code`   | `bc_stock`   | The paper choice |

**Variants are not configuration.** Sides, shape, corners and paper are what the shopper chose. They stay on the product as ordinary variants because they carry price, and the tool reads them live and writes back to them — so changing the paper inside the tool moves the price, and changing it on the product page updates the tool.

***

### How to check what the tool actually received

Load the product page and inspect `<div id="bc-root">`.

Every setting appears twice: once as its value, once as a `-source` attribute saying where that value came from.

```
data-placement          = AUTO
data-placement-source   = mount_arg
```

* `mount_arg` — the mount passed it.
* `default` — the mount did not, and the built-in default is in use.

Anything the mount did not pass is also listed in `data-config-missing`, and the tool reports it in the browser console as an error naming each missing setting by name.

**A default is not an error.** The defaults are correct for a standard business card. The point of `data-config-missing` is that a setting you *meant* to pass and mistyped shows up as missing rather than quietly falling back.

***

### Settings that no longer do anything

If this store was set up before September 2026, it may still carry configuration the tool no longer reads. None of it does any harm, and all of it can be deleted.

| Leftover                                   | Status                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `admin/checklist/business-card-*` snippets | **Read by nothing.** There were sixteen of them, under Custom Admin. Every one is now a mount argument              |
| Product custom fields named `bc_*`         | **Read by nothing.** `product` is not in scope in a `custom_script` mount, so these were never capable of resolving |
| Design custom fields named `bc_*`          | **Read by nothing**, for the same reason one level down                                                             |

The only custom field the tool depends on is `custom_script` itself, on the `bc_artwork_front` template option.

Before deleting anything, confirm nothing else on the store reads it. A checklist snippet or custom field named for the business card tool may still be referenced by a theme customisation.

***

### Related

* Business Card tool: setup and activation
