The claim button

Unclaimed listings show a Claim Listing button in the app. Its state follows the Claim Listings module’s own rules:

• Claimable — the listing has at least one category and is still owned by the unclaimed-user account, with no overriding claim rows.
• Request / Purchase — free claims request access; paid claims open the purchase screen.
• Pending — the user already holds a pending request or an approved claim awaiting payment.

Status is read through the module API (object-cached), never raw SQL.

Free claims

A free claim submits a request, then an admin approves or rejects it from the app’s approvals queue. Whether a request needs approval follows the Business Directory module’s own claim default status setting — there is one source of truth, no separate MAM option. Free directories auto-complete on approval and the claimant becomes the owner.

On approval/rejection, business-directory-claim-approved / business-directory-claim-rejected notify the claimant; business-directory-claim-requested and business-directory-listing-claimed notify admins.

Paid claims

Paid claim options are the Business Directory fee plans whose categories match the listing (wpbdp_get_fee_plans). The purchase screen uses your Claim Listing tab appearance settings (CTA, features, colors) and the checkout colors for Stripe.

• Stripe (mam_claim_listing_paid) and In-App Purchase (mam_claim_listing_iap) both complete the claim through a real Business Directory payment (payment_type 'claim'). Completing the payment transfers ownership and assigns the fee plan via the module/core hooks — you get Business Directory’s payment ledger and receipts for free.
• Completion is idempotent (deduped on the gateway transaction id) and the submitted plan is validated against the listing’s eligible plans, so a client cannot substitute a cheaper or unrelated plan.

$0-plan caveat: a $0 enabled plan matching the listing’s categories completes a claim without approval. Do not configure one if approval matters.

When a subscription lapses

Two crons are involved:

• The module’s daily maintenance cron auto-rejects approved-but-unpaid claims after the module’s unpaid-release window (default 30 days) — this is upstream of purchase.
• Our mam_bd_claim_iap_lapse_check cron handles post-purchase lapse: when an IAP subscription lapses it downgrades the listing to a free plan, or alerts admins (business-directory-claim-lapsed) when there is no free tier to fall back to.

Related articles

• Recipe: Fee-plan MAM fields
• Recipe: Bulk-invite venue owners to claim
• Listing tab bar buttons
• Business Directory notification types
• Business Directory integrations

Metadata