For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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

Add arguments by comma-separating them:

{% 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.

  • 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.


  • Business Card tool: setup and activation

Last updated