Overview
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.
Installation
Follow the installation steps to get started.
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.
Users who want to claim their listing must be registered on your site.
Listings that can be claimed have a Claim this listing link on top of them. If the user is registered and logged in, 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.
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
- User submits a listing claim via the form available on top of unclaimed listings:
- Admin is notified by e-mail of the new listing claim (optional).
- Admin goes to the “Claim Listing” dashboard where the list of claims is displayed.
- 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.
- 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.
- (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.
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:
Notes
- 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 → Settings → 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:
General Settings:
- Default owner of ‘Unclaimed Listings’ – Listings having this user as author are considered unclaimed (see above) and are subject to accept listing claims. Listings having a user other than this one are considered claimed. They will not show the “Claim this Listing” link when displayed on your site. The admin is typically the default user for this purpose of “unclaimed” listings.
- Notify Admin of New Claims?: Turn this on to receive emails from your directory when a user attempts to claim a listing. This is useful if you want to know when to check claims that are pending.
- Claim Listing Templates
- Approval email: The email sent to the user when their claim is approved and paid for. Only sent if the user is required to pay for a listing and they are approved.
- Approval email (no payment): If your listings do not require payment, this is the email that is sent instead when a claim is approved.
- Rejection email (if reason is provided): Email sent to the user when you reject the claim and provide a reason.
The Claim Listing form section allows other options to be configured:
- Put reCAPTCHA on the claim form? – Because of possible spam, you may wish to enable Google's reCAPTCHA to show up on the form to avoid bots from submitting fake claims. Requires that you have the reCAPTCHA API keys setup in Directory → Settings → General → SPAM tab to use this.
- 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.
- Make “Claim Reason” required? – If the user submits a claim, do they have to provide a reason? If so, turn this option on.
- “Claim Reason” field label – Specific label text you can use instead of “Claim Reason” for the reason why they are claiming this business.
- Request Received Text – This is the message 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.