Metafields

In addition to the Cardigan configuration managed with the application, you can augment your Shopify resources with additional metadata to further customise Cardigan's functionality. This is achieved by adding metafield data to your products and variants.

All of Cardigan's metafields live in the cardigan namespace, and Cardigan picks up changes automatically as you edit your products.

Most metafields will be set by hand in the Shopify admin, following the instructions below. In some instances (such as when setting cart-level restriction metafields), it's expected the metafields are set by your own custom code.

Defining a metafield in your store

Before you can set a value, Shopify needs to know the metafield exists. This is a one-off step per metafield, done in your Shopify admin rather than in Cardigan.

1. Go to Settings → Custom data, then choose Products or Variants depending on where the metafield is set. The table below tells you which.
2. Click Add definition.
3. Fill in the definition:
   • Name is free text and is what you'll see on the product page. Pick something readable - the names in the table below are a reasonable starting point.
   • Namespace and key must be entered exactly as given in the table. This is what Cardigan looks for.
   • Type must match the table.
4. Save.

The metafield now appears in the Metafields card at the bottom of every product (or variant) page, ready for you to set a value on the items you want it to apply to.

Available metafields

The first three affect the cards you issue, and only apply to gift card variants. The rest affect how customers can pay, and apply to any product at all.

The two Cart rows are the exception to everything in the section above: they aren't defined in Settings → Custom data and can't be set by hand on a product. They're written by a custom checkout UI extension in your online checkout - see Cart-level restrictions.

Preventing payment by gift card

Setting cardigan.ineligible_for_gift_card to true marks an item as something a customer can't pay for with a gift card.

Two situations come up often enough to be worth naming:

• Physical gift card products that Cardigan doesn't provision. A product representing a physical card on a shelf isn't part of your matching configuration, so it isn't caught by the automatic block - but selling one in exchange for gift card funds has the same problem.
• Products susceptible to fraud. Anything easily resold, where paying with a gift card of uncertain origin is a risk you'd rather not take.

What the customer sees

When a cart contains an ineligible item, the Cardigan gift card block at checkout shows a short explanation in place of the card entry form. If the customer had already applied a card before adding the item, the card is removed and the reason explained, and they can't complete the checkout until either the card or the item is gone.

Customers not using a gift card are unaffected and check out normally.

Products and variants

Set it on the product to cover every variant, or on a variant for finer control.

A variant value overrides its product in both directions. A variant set to false stays payable by gift card even when its product is marked ineligible - useful when a single variant is the exception rather than the rule.

Items with no value set at all are payable by gift card, exactly as before.

Cart-level restrictions

Marking individual products covers most cases, but some reasons for refusing a gift card have nothing to do with what's in the cart - a particular kind of customer, a discount code that shouldn't be combined with gift card payment, a rule that only your own systems know about.

For those, Cardigan reads the same ineligible_for_gift_card flag from the cart instead of from a product. Anything that can write a cart metafield can switch the block on, and can supply its own wording to explain it.

Setting the flag

From a checkout UI extension, write the metafield on the cart:

applyMetafieldChange({
  type: 'updateCartMetafield',
  metafield: {
    namespace: 'cardigan',
    key: 'ineligible_for_gift_card',
    value: 'true',
    type: 'boolean'
  }
});

true blocks the checkout's gift card form exactly as an ineligible product does. false, an empty value, or no metafield at all leaves the checkout alone, so a rule can be switched off again by writing false rather than deleting anything.

Supplying your own message

Cardigan's default wording is deliberately vague, because it has to be true whatever the reason. Writing cardigan.ineligible_message replaces it:

applyMetafieldChange({
  type: 'updateCartMetafield',
  metafield: {
    namespace: 'cardigan',
    key: 'ineligible_message',
    value: 'Staff discount cannot be combined with gift card payment. Please remove one or the other.',
    type: 'single_line_text_field'
  }
});

The message replaces the default for any reason a gift card is refused as ineligible - a gift card product in the cart, an ineligible product or variant, or the cart-level flag. So it can be used to reword the product-driven block too, without setting the flag at all.

A few practical limits:

• Messages longer than 200 characters are truncated.
• The text is shown to the customer exactly as written, so it's your job to translate it. Your extension knows the buyer's locale; Cardigan's own wording is already translated, and is used whenever you don't supply a message.
• Declaring the same namespace and keys in your own extension's [[extensions.metafields]] does no harm, and lets you read back what you wrote.

Which value wins

Two rules, both of which resolve in favour of the more specific setting:

• Where the same value can come from either a line item property or a variant metafield, the line item property wins - so a customer's choice at the point of purchase takes precedence over the variant default.
• Where a value is set on both a variant and its product, the variant wins.

The cart-level flag sits outside that hierarchy: if it's set to true, the checkout is blocked whatever the individual products say.