How to set card backgrounds for dynamic store.get items and bundles in custom templates

When using dynamic products returned from the store.get webhook, card backgrounds are controlled by the data you return in the webhook response.

Key behavior

• For dynamic items, an image background can be set by explicitly passing background_image_url on the item data.

• If you set a background on a bundle/offer itself, that background applies to the bundle artwork for that offer.

• If the offer does not use bundle artwork and instead displays the individual rewarded items, set background_image_url on the individual item entries that are being displayed.

• If all regular products are currently using card_type: featured, consider switching standard products to card_type: default. Featured cards are typically used only for highlighted products and are displayed wider than default cards.

When to use Item vs BundleItem

• Use Item for single products.

• Use BundleItem for actual bundles that contain multiple nested items.

Recommended setup for bundles

• Bundle with multiple products: use card_type: featured and provide the imagery/backgrounds for the displayed nested items.

• Bundle with a single product: use card_type: default and set image_url and background_image_url on the bundle itself rather than relying on nested item presentation.

This distinction matters because a background set on the parent bundle affects the bundle artwork. If the UI is rendering the individual rewards instead, the background needs to be attached to the item data that is actually shown.

Example: single dynamic item with a background glow

{
  "sku": "my_item",
  "name": "My Item",
  "card_type": "default",
  "background_image_url": "https://example.com/background-glow.webp"
}

Example: bundle with a single product

For a single-product bundle, put the visual fields on the bundle itself.

{
  "sku": "single_reward_bundle",
  "name": "Single Reward Bundle",
  "card_type": "default",
  "image_url": "https://example.com/reward.png",
  "background_image_url": "https://example.com/background-glow.webp",
  "nested_items": [
    {
      "sku": "reward_1",
      "quantity": 1
    }
  ]
}

Example: bundle that displays nested items

If the UI is showing the individual rewarded items instead of bundle artwork, apply the background to the individual displayed items rather than only to the parent bundle.

{
  "sku": "my_bundle",
  "name": "My Bundle",
  "card_type": "featured",
  "nested_items": [
    {
      "sku": "reward_1",
      "name": "Reward 1",
      "background_image_url": "https://example.com/background-glow.webp"
    },
    {
      "sku": "reward_2",
      "name": "Reward 2",
      "background_image_url": "https://example.com/background-glow.webp"
    }
  ]
}

Custom template styling

Visual changes such as outlines can be implemented in a custom template. However, for dynamic item backgrounds, the supported approach is to return the background image URL in the store.get response for the relevant displayed item data.

Adjusting the internal margin between the item artwork and its outline is not something that can currently be changed through the template itself. The practical workaround is to add transparent padding around the item artwork image so it does not sit directly against the outline.

Aghanim can also increase spacing between items in the overall grid, but that is separate from the padding inside each individual item image.

Category behavior

Once this custom category treatment is configured as the default for the store categories, it applies to all existing categories and the fallback items category.

New store categories created later will also inherit that same default treatment automatically, so you do not need to ask support each time you add a new category.