Claim Listings module


The Claim Listing module allows admins to create listings for known companies or services and then charge users a fee to become the actual owners of those listings. This allows said users to edit listing information, answer messages from customers, etc.

The whole process is regulated and subject to admin approval.

Basic Concepts

The module uses a very easy convention to distinguish between listings that can be claimed and those that can’t: the module considers one special user, usually the admin, as the owner of “unclaimed” listings (see Module Settings). This means that listings from different authors can’t be claimed by anyone.

Listings that can be claimed have a Claim this listing link on top of them. Clicking the link reveals a form where users must enter some information before requesting ownership of the listing. Once this form is submitted a listing claim is created.

A listing claim refers to an ownership request from a particular user for a particular listing. Listing claims have statuses associated to them (see Claim status below): they begin as “Pending” (meaning the admin hasn’t seen the claim) and end up as either “Rejected” or “Completed”. A completed claim results in the user making the request being the author of the listing.

All of these concepts are more clearly illustrated in the Claim Workflow section below.

Claim status

Once a listing claim is submitted it can have one of several possible statuses:

  • Pending – The claim has been submitted but it hasn’t been approved or rejected by the admin. Until this claim is resolved the listing is not available for other users to claim.
  • Rejected – When the admin decides not to approve the claim. At this point the listing is released for other users to submit claims.
  • Approved – When a particular claim is approved the user receives an e-mail notification including instructions on how to proceed from there. At this point no other user can submit a claim for the same listing but it still doesn’t mean the user of the approved claim owns the listing. The user still needs to confirm the claim and pay the listing fees. Not doing so results in the claim being automatically rejected after some configurable number of days (see settings).
  • Completed – User paid for the listing fees and it’s now the author of the listing, being able to make edits, etc.

Listing “claim” status

When the Claim Listings module is enabled, listings gain a “Claim Status” field.

An unclaimed listing

This field can have one of the following values:

  • Claims Pending – The listing has received listing claims that need to be reviewed, i.e. there are claims with “Pending” status.
  • Pending Payment – The listing claim from a particular user was approved by the admin but the user hasn’t paid the listing fee to become the owner of the listing. The claim has the “Approved” status but the listing still belongs to the admin.

    The listing retains this status until either the user pays the fee (changing the claim status to “Completed” and the listing status to “Claimed”) or the claim is automatically dropped by the system after some time of inactivity (no payment).

  • Claimed – The listing has been claimed by a user and the user is the owner of the listing (author). The claim resulting in this should have the “Completed” status.

Claim Workflow

  1. User submits a listing claim via the form available on top of unclaimed listings: Claim Listing form Claim Listing form submitted
  2. Admin is notified by e-mail of the new listing claim (optional).
  3. Admin goes to the “Claim Listing” dashboard where the list of claims is displayed. Claim in admin
  4. The admin approves or rejects the claim directly from this screen or goes into the detailed view to see more information for any claim. On the detailed view admins can also contact the user making the claim to request further information before deciding what to do.

    Claim in admin

  5. Admin approves or rejects the claim:
    • If the claim is rejected and the admin provided a reason for that, the user is informed via e-mail. If not, it’s just silently rejected. If there are no more pending claims for the listing, the listing is released again and can be claimed by other users.
    • If the claim is approved an e-mail is sent to the user including a link to a page where the listing fee has to be paid before becoming the owner of the listing.

      Approve claim dialog

  6. (Only after an approved claim) The user follows the link from the approval e-mail and pays for the listing in order to become its author and be able to edit and manage the listing.

    Claim confirmation page

    If the user doesn’t want to continue with the process this screen also offers the chance to withdraw the claim. After the payment is confirmed the listing now belongs to the user making the claim and the listing is considered claimed:

    Listing claimed


  • Even though users are offered the chance to withdraw their claims after approval (see above), this would’ve happened automatically after some days of inactivity (no payment). This threshold can be configured by admins.
  • Claimed listings are regular listings. That means they are subject to the expiration or upgrade rules as other listings depending on how they were created.
  • Transactions resulting from listing claims appear as regular transactions associated to the listing. Admins can manually approve them or reject them as with other payments.
  • Claims can also be deleted by admins. This is a silent operation and it doesn’t affect the current state of listings or other claims.

Module Settings

Settings for the Claim Listings module can be found inside Directory Admin - Manage Options - Claim Listings. On this page, you’ll find that all settings include a clear description of what they do, but let’s discuss some important ones:

  • Default owner of ‘Unclaimed Listings’ – Listings having this user as author are considered unclaimed (see above) and are subject to receive listing claims. Listings having a user other than this one are considered claimed.
  • Show a “Claim Reason” field? – When a user is submitting a listing claim you can use a “Claim Reason” field to capture additional information to support the claim.
  • Request Received Text – This is the text that is displayed to users once the listing claim form is submitted.
  • Days before releasing claimed listings pending payment? – As explained above once a listing claim is approved, the user submitting the claim has to pay the listing fees to become its owner. This setting controls how many days to wait for this payment before considering the listing unclaimed again and rejecting the user’s claim.