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
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
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
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:
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:
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
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.
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.
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
Last updated