Skip to main content
Glama
Sign In
erayendes

Heimdall App Store Connect MCP

by erayendes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

pricing__make_offer

Destructive

Create subscription win-back, promotional, or introductory offers for every App Store country from one anchor price or free trial, with dry-run validation and resumable introductory writes.

Instructions

Make a subscription win-back, promotional or introductory offer, priced in every country where the subscription is sold, in one call. Give the app, the subscription, the offer kind, mode, duration and periods, and either an anchor territory and price or a free trial. Every other market comes from Apple's own equalizations of the anchor. Win-back and promotional offers go to Apple as one request, so they exist complete or not at all. Introductory offers are one write per country, taking a few minutes: everything is checked first, it stops at the first failure, and the same call again resumes. Once made, only an introductory offer's end date can change. Refuses without writing when any country is missing a price. REVENUE-level write; run it under --dry-run first to see the full derived table.

Input Schema

NameRequiredDescriptionDefault
appYesApp name, bundle ID (com.example.app) or numeric Apple ID.
nameNoWin-back and promotional, required: reference name, seen only in App Store Connect.
undoNoIntroductory only. true takes back an introductory offer this tool set: with the same terms, price and dates as the original call, it deletes that exact offer in every country carrying it, one country at a time, and touches no other offer.
priceNoPaid offers: customer price in the anchor territory's currency, e.g. "29.99". Must match an Apple price point exactly; the nearest available are suggested if it does not.
periodsYesNumber of periods. 1 for PAY_UP_FRONT and FREE_TRIAL.
durationYesLength of one offer period (PAY_AS_YOU_GO) or of the whole offer.
end_dateNoThe offer's end date (YYYY-MM-DD), win-back and introductory only. Omit for open-ended.
offer_idNoWin-back and promotional, required: the identifier the app uses for this offer (Apple's offerId for win-back, offerCode for promotional). Must not be used by any other offer of this subscription.
priorityNoWin-back only: how Apple ranks it against other offers. Defaults to NORMAL.
territoryNoPaid offers: the anchor country, three letters (ISO-3166 alpha-3): TUR, USA, DEU. Every other country is derived from it.
offer_modeYesPAY_AS_YOU_GO: the price is charged every period, for `periods` periods. PAY_UP_FRONT: the price is charged once for the whole duration. FREE_TRIAL: no price; leave territory and price out.
offer_typeYeswin_back: shown to lapsed subscribers who meet the eligibility below. promotional: redeemed by existing or lapsed subscribers through a signed offer in the app. introductory: the first period for customers new to the subscription group.
start_dateNoFirst day the offer runs (YYYY-MM-DD). Required for win-back; optional for introductory (omit to start now); not used for promotional.
subscriptionYesSubscription product ID (e.g. com.example.pro.yearly) or its reference name.
eligibility_paid_monthsNoWin-back only, required: how many months the customer must have paid for before.
eligibility_wait_monthsNoWin-back only, optional: months before the same customer can redeem this offer again.
eligibility_last_subscribed_max_monthsNoWin-back only, required: most months since the customer's subscription lapsed.
eligibility_last_subscribed_min_monthsNoWin-back only, required: fewest months since the customer's subscription lapsed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.8.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations (destructive=true, idempotent=false) by disclosing atomicity per offer type: win-back/promotional are one all-or-nothing request, introductory is one write per country taking minutes, checks first, stops at first failure and resumes on re-invocation. It also states immutability ('once made, only an introductory offer's end date can change') and the REVENUE-level write privilege required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then conditional behaviors, then guardrails and the dry-run caveat. Dense but every sentence carries operational information for an 18-parameter financial write; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, revenue-level, 18-parameter mutation with no output schema, the description covers what an agent needs before committing: prerequisites, atomicity, failure/resume behavior, mutability limits and the dry-run escape hatch. Return-value detail is unnecessary since no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, and the description earns a step up by explaining the relational contract between parameters: app + subscription + offer kind/mode/duration/periods plus either an anchor territory+price or a free trial, with all other markets derived from Apple's equalizations of the anchor. It doesn't add syntax details beyond what per-parameter schema text already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Make a subscription win-back, promotional or introductory offer') and adds scope ('priced in every country where the subscription is sold, in one call'). This clearly separates it from the pricing__set_subscription_price / equalize_price siblings that operate on a single price or territory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operating context: run under --dry-run first, and it refuses without writing when any country lacks a price. It does not, however, explicitly route the agent between this tool and sibling pricing tools, nor state when an offer should be made via this tool versus a plain price update.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools