In game purchases skill for AI agents

​

When your agent uses it

• Adding a shop, buy button or paid item to a Summer game and wiring request_checkout
• The player does not have enough Sparks (checkout rejected with insufficient_funds) and the game should tell them how to buy more Sparks
• Deciding whether an item should be sold for Sparks, or handling pending, declined, expired, rejected or manual_review purchase results

​

Install

npx -y summer-engine@latest skills install in-game-purchases --agent claude-code

​

The skill

​

When to sell with Sparks

• Sell anything that persists across sessions or devices (cosmetics, unlocks, passes) as a Summer item with a Sparks price. Why: the platform owns the item, so ownership survives reinstalls and cannot be forged by editing the game.
• Do not invent your own currency that is bought with money. Why: Summer can only refund, protect and pay you out for Sparks purchases.
• Open the shop only from an explicit shop or buy button. Why: the Summer sheet interrupts play; surprise payment prompts read as pressure and get games reported.

​

Rules and the reason for each

1. Never grant an item from a button press or a receipt. Unlock only when Summer.client.items shows the player owns it. Why: the receipt proves the debit; the inventory projection is what the platform guarantees the player owns, including after a crash or on another device.
2. Never send prices or amounts. The game passes an offer ID and a quantity (SummerCheckoutLine.create(offer_id, quantity)). Why: the platform prices everything; a client-supplied price is exactly what a cheater edits.
3. One call is one purchase. Every request_checkout creates a new identity. Never call again to “retry” an unknown outcome (SummerCheckoutOperation.is_outcome_unknown()). Why: the first request may already be charged; the SDK recovers it and delivers the result on the signal.
4. Handle results in checkout_status_changed, and deduplicate by request_id plus version. Connect normally (not deferred) before requesting. To draw a checkout panel, read get_checkout_statuses() and has_pending_checkouts() instead of keeping your own list. Why: results can arrive after a restart or twice after a crash; a synchronous handler is how the SDK knows the result was delivered.
5. Treat manual_review and pending as not done. Why: the platform has not decided yet; showing success or failure would be a guess.
6. Check readiness and hide what is unavailable. check_checkout_readiness() (buying) and check_browse_readiness() (listing with list_items()) return a SummerResult. Why: editor play, guest sessions and older Summer apps do not offer purchases; a dead button is worse than no button.

​

Result states

​

Minimal complete example

extends Node
## A one-item shop. Buys `offer_id` and unlocks from inventory.

@export var offer_id := "offer_sword"
@export var definition_id := "item_sword"

signal message(text: String)
var _seen := {}

func _ready() -> void:
	if Summer.client == null:
		return # not running as a player's game
	Summer.client.store.checkout_status_changed.connect(_on_checkout)
	Summer.client.items.refreshed.connect(_sync_owned)
	_sync_owned()

func buy() -> void:
	if not Summer.client.store.check_checkout_readiness().ok:
		message.emit("The shop is not available here.")
		return
	var lines: Array[SummerCheckoutLine] = [SummerCheckoutLine.create(offer_id, 1)]
	Summer.client.store.request_checkout(lines) # result arrives in _on_checkout

func _first_time(status: SummerCheckoutStatus) -> bool:
	var key := "%s:%d" % [status.request_id, status.version]
	if _seen.has(key):
		return false
	_seen[key] = true
	return true

func _on_checkout(status: SummerCheckoutStatus) -> void:
	if not _first_time(status):
		return
	match status.state:
		&"purchased":
			Summer.client.items.refresh() # ownership comes from inventory
		&"rejected":
			if status.error_code == &"insufficient_funds":
				message.emit("Not enough Sparks. Get Sparks in the Summer app, then buy again.")
			else:
				message.emit("The purchase was not completed.")
		&"manual_review":
			message.emit("We are confirming this purchase.")
		&"declined", &"expired":
			pass

func _sync_owned() -> void:
	if Summer.client.items.has_owned_definition(definition_id):
		message.emit("Sword unlocked.") # the only place the item is granted

​

Multiplayer: granting an effect on a dedicated authority

1. reads that player’s inventory with Summer.authority.items.inventory_for_session(session) and checks the item is there, owned, and of the right definition;
2. checks its own record of redeemed item IDs, kept in the player’s secret player data (Summer.authority.player_data), so the item grants once per player in every world;
3. writes the new record, and applies the effect only after that write succeeds.

# On the dedicated authority.
const EFFECT_DEFINITION := "item_grow_now"

func redeem(session: SummerSession, owned_item_id: String) -> void:
	var inv := Summer.authority.items.inventory_for_session(session)
	var read: SummerResult = await inv.get_result_or_completed_signal()
	if not read.ok:
		return # unavailable: the client may ask again later
	var item: SummerInventoryItem = null
	for candidate in inv.items:
		if candidate.get_owned_item_id() == owned_item_id:
			item = candidate
	if item == null or not item.is_owned() or item.get_definition_id() != EFFECT_DEFINITION:
		return # not owned by this player: never grant

	var load_op := Summer.authority.player_data.load(session)
	var loaded: SummerResult = await load_op.get_result_or_completed_signal()
	if not loaded.ok:
		return
	var data: Dictionary = load_op.secret_record.data
	var redeemed: Dictionary = data.get("redeemed", {})
	if redeemed.has(owned_item_id):
		return # a repeated message grants once
	redeemed[owned_item_id] = true
	data["redeemed"] = redeemed
	var save_id := "redeem_" + owned_item_id.sha256_text().substr(0, 40)
	var commit := Summer.authority.player_data.commit_secret(session, save_id, data)
	var saved: SummerResult = await commit.get_result_or_completed_signal()
	if not saved.ok:
		return # retryable: commit again with the same save_id
	apply_grow_now(session)

• The save ID comes from the owned item ID. Why: resending the same save ID with the same content returns the earlier commit (commit.replayed), so a retry after a timeout records the redemption once.
• Apply the effect when the commit succeeds even if commit.replayed is true and the effect is not in your world yet. Why: a replay means the redemption was recorded earlier, but your world may have crashed before it applied the effect.
• The engine has no call that uses up an owned item. The item stays in the player’s inventory after it is redeemed; the redeemed list is what stops a second grant. Show redeemed items as used in your UI.

​

Idempotency

​

Per-surface behaviour

• Summer Games app on iOS: a native Summer sheet over the game.
• Summer desktop app: an overlay sheet; the result returns to the game on the signal.
• Web: the same sheet in the page.
• Editor play and local runs: readiness is unavailable. Build the unavailable path first.

​

Testing

• Test against Summer staging, which runs in sandbox mode. Why: no real money moves and results are identical to production.
• Walk every state: decline the sheet, let it expire, buy with too few Sparks, get Sparks in the Summer app, then buy the item. Kill the game while a checkout is pending and relaunch; the result must still arrive once.
• Verify the unlock comes from items.refreshed, not from the checkout signal.

​

Store policy notes

• Apple requires In-App Purchase for digital goods and currency sold inside iOS apps. Summer’s iOS sheet and app handle this; never add your own payment links, web prices or “cheaper on the web” text inside the game. Why: it can get the Summer app removed from the App Store for every game.
• Randomized paid rewards must disclose their odds before purchase (Apple and most regions require it).
• Say what a purchase gives in plain words next to the price.

​

Availability

​

See also

• multiplayer-state
• ui-basics

​

From a shell

​

Related skills

• multiplayer-state: Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events.
• ui-basics: Build UI: HUDs, menus, health bars, dialogue boxes, Control trees, anchors, containers and themes.