Piggy bank offers

What's new

Piggy banks are a new item type. The ItemType enum gains a piggy_bank value, and a new PiggyBankRead schema describes the offer itself. It carries the usual item fields (name, sku, price, currency, images, nested_items) plus:

• id — the piggy bank offer ID.
• title, start_at, end_at — the offer's display title and availability window.
• settings (required) — a PiggyBankOfferSettings object:
  • custom_attribute (required) — the player custom attribute the piggy bank's progress is read from.
  • tiers (required, at least one) — a list of PiggyBankTier objects, each with a tier_value, the items unlocked at that tier (item_id, optional quantity and sku), an optional icon_url, and optional bonus_items_settings applied after purchase.
  • image_url, background_image_url, background_size — the look of the offer block.
• nested_items_read — the resolved child items.

Store items can now hold a piggy bank offer. StoreItemRead adds PiggyBankRead to its item union and gains an object_type field (item, lootbox, subscription, virtual_currency, or piggy_bank_offer, default item) that says what the card holds.

Impact

get_items and the store item endpoints can return piggy bank offers alongside regular items, lootboxes, subscriptions, and virtual currencies. The spec adds no endpoint or request schema for creating a piggy bank offer's tiers and settings, so these fields are read-only for now.

Changes

Resource	Change
get_items	Added PiggyBankRead to the oneOf of the 200 response items
get_store_items, get_all_store_items, create_store_item, update_store_item, bulk_update_store_items	Added PiggyBankRead to the item union and the new object_type field on the response
create_item, update_item, bulk_update_items, bulk_create_or_update_items	type accepts piggy_bank
get_item, get_player_store_items, coupon, daily reward, and loyalty tier endpoints	type on returned items and nested items can be piggy_bank
Components	Added PiggyBankRead, PiggyBankOfferSettings, PiggyBankTier, PiggyBankTierItem, and StoreItemObjectType

Upgrade

• Clients that decode item type into a closed enum should add piggy_bank, or a strict decoder will reject responses that contain one.
• Clients with generated models for the get_items or store item unions should regenerate to pick up PiggyBankRead. To tell a piggy bank card apart without inspecting the item, read the store item's object_type.

Need help?
Contact our integration team at [email protected]