Goal

Understand how Claim Listing works so you can configure it confidently and diagnose issues. For step-by-step setup, see Recipe: Set up Claim Listing subscriptions.

The big idea: a claim creates a native GeoDirectory pricing subscription. GeoDirectory owns the subscription record, the package assignment, and the listing ownership. MAM provides the in-app screens and the two payment rails (Stripe or In-App Purchase) that feed that native flow. Because everything lands as a normal GeoDirectory subscription, claim / upgrade / downgrade / cancel behave the same on web and in the app.

The claim button — three states

The button on a listing’s detail screen is built by mam_gd_claim_listing_manager. It is hidden when the listing isn’t claimable, is already claimed, the viewer is the author, or no one is signed in. When visible, it takes one of three forms:

Which form shows depends on the mode:

• Direct purchase mode (approval off, or no free package exists): the button is Claim Listing.
• Approval mode (approval on and a free package exists): the button is Request to Claim until the user owns the listing.

Approval mode deliberately requires a free package. That lets approval lean entirely on GeoDirectory’s native Claims dashboard: approving grants the user the free tier, and they upgrade to a paid package in-app afterward. If no free package exists, the toggle is ignored and the app shows direct purchase.

Flow A — Direct purchase

1. The user taps Claim Listing, picks a package, and pays on the chosen rail.
2. The app posts the order. The claim order handler:
   • Creates the GeoDirectory claim invoice (routed to the Invoicing/GetPaid cart).
   • Saves the pending claim, linked to that invoice.
   • Charges the invoice through the rail’s GetPaid gateway (below).
3. On payment, GeoDirectory’s bridge auto-approves the claim: it re-points the listing’s author to the buyer, marks it claimed, assigns the package, and activates the subscription.
4. All admins receive the Listing Claimed notification. The app returns to the reloaded listing (now owned, claim button gone).

Flow B — Request and approve (approval mode)

1. The user taps Request to Claim and confirms. A pending claim is created and tied to the free package. All admins receive the Claim Requested notification. The button now reads Claim Pending.
2. You review the request in GeoDirectory’s own Claims dashboard and Approve or Reject it.
3. On Approve, GeoDirectory makes the user the owner at the free tier, and the claimant receives the Claim Request Approved notification (which opens the venue). On Reject, they receive the Claim Request Rejected notification.
4. The user can later upgrade to a paid package using the in-app package selector.

The two payment rails

A claim invoice is charged by a MAM GetPaid gateway, chosen by your Checkout mode setting. Both produce the same native GeoDirectory subscription — they differ only in who collects the money.

Stripe rail (mam_stripe)

Charges the customer’s saved card off-session through MAM Stripe, then marks the invoice paid. MAM Stripe / GetPaid own the recurring billing: renewals are charged automatically on schedule, and the subscription can be managed on the web. The user must have a saved card.

In-App Purchase rail (mam_iap)

The App Store / Google Play collect the money and own the renewal billing. The MAM IAP gateway therefore never charges — it validates the purchase and marks the invoice paid, which triggers the same GeoDirectory bridge. Each claim package maps to a store subscription product (via the WooCommerce product’s SKU).

Why a gateway at all for IAP? So an IAP claim becomes the same native GeoDirectory subscription as a Stripe claim. The management layer (and web/app parity) stays uniform; only the billing source differs.

IAP renewals and lapses

Because the store owns IAP billing, MAM mirrors the store’s state rather than driving it:

• Renewals are billed by Apple/Google. The app reports the current expiry when it reopens, and the MAM In-App Purchase Manager records it.
• Lapses are caught by a daily check. If a claimed listing’s IAP subscription has lapsed past a short grace window, MAM downgrades the listing to the free tier (keeping the user as owner) when one exists, or — if there’s no free tier — sends the Claim Subscription Lapsed notification to admins to handle manually.

Trade-off (by design, for these low-value subscriptions): a cancel or refund made in the App Store by a user who never reopens the app isn’t noticed until the next check. Server-to-server store notifications can be added later if a deployment needs tighter accuracy.

Notifications at a glance

Configure their templates as described in GeoDirectory notification types.

What the app receives

The Claim Listing button payload carries the mode (stripe/iap), the post id, the call-to-action and features text, the appearance colors/background, and the package list. Each package includes its package_id, the WooCommerce product_id, the store sku (used by the In-App Purchase rail), the formatted price, and the recurring term label.

Verification

This article was last verified against:

• Plugin: mam-geodirectory 26.26.0
• Sources: includes/mam_gd_claim_listing_manager.php, includes/mam_gd_claim_order_handler.php
• Gateways: GetPaid_MAM_Stripe (mam-stripe-manager), GetPaid_MAM_IAP (mam-inapp-purchase-manager)
• Required: GeoDirectory Claim Listing + Pricing Manager add-ons, GetPaid/Invoicing

Re-verify whenever the claim button states, the approval model, the payment rails, or the notification slugs change.

Related articles

• Recipe: Set up Claim Listing subscriptions — step-by-step configuration
• Plugin: mam-geodirectory
• Recipe: Pricing package fields
• Integration: In-App Purchase Manager
• GeoDirectory notification types
• Mobile listing data shape — claim_status and can_claim keys

Metadata