Listings

This page describes listings and their different mechanisms. It is possible to create listings for both online and face-to-face transactions.

Listings vs Transactions

In a nutshell, listings are blueprints for transactions, and they allow you to create multiple transactions from one "blueprint". Transactions allow you to perform a once-off exchange with an individual, but listings allow you to create multiple transactions - all with the same description and pricing. As such, listings have a one-to-many relationship with transactions:

When a user "joins" a listing, this means that a new transaction is created involving that user and the user that created the listing, and the new transaction will have all of the details (description, price, etc.) from the original listing.

An important note is that transactions created from listings are not updated when the source listing updates. This prevents listing owners from changing the details of transactions after the other party has joined the transaction. As an example, if a user creates a listing for "Tennis Tickets" and another user joins it, if the listing owner updates the listing description to "Badminton Tickets" then transactions created after that point will have the "Badminton Tickets" description, but the original transaction will still have a "Tennis Tickets" description:

Disabling Listings

Transactions can't be created from disabled listings. Listings can be disabled and re-enabled by the owner at any time. See the section below on "Single-use vs Multi-Use" for details on how listings can be disabled automatically.

The "disable" mechanism of listings is simple in order to support different kinds of functionality. For example, stock-based functionality can be implemented by your application to automatically disable a listing once a certain number of users have joined it or paid for it.

Single-Use vs Multi-Use

The only difference between a single-use listing and a multi-use listing is the time at which they get automatically disabled.

A multi-use listing never gets disabled automatically - the owner must disable it manually in order to prevent other users from joining it.

A single-use listing gets disabled once a transaction created from it gets paid for in full (i.e. once the final payment is made). This is an important point in the case of face-to-face transactions, where there can be 2 payments involved. In this case, multiple users can join the same single-use listing and pay a deposit for the item, but the listing will only get disabled once a user pays for it in full. This approach avoids the situation where a user has to re-enable a listing because the transaction created from it was abandoned. By waiting until the final payment has been made, a single-use listing remains open until the item it advertises has been sold.

Listings for Online Transactions

Online transactions created from listings have an additional step that is not present in regular online transactions. This step gives the listing creator an opportunity to opt out of a transaction created from one of their listings. For example, if the item that a seller listed has been sold offline, then this gives the listing creator the opportunity to cancel a new transaction before payment is made.

To handle this case for online transactions, check if the status is joined and if the transaction has a listing_id property. If both of these are true, and the transaction doesn't have a accepted_by_listing_creator property, then the creator of the listing needs to accept the transaction before it can proceed. The listing creator can then accept the transaction or they can reject the transaction.

If the listing creator accepts the transaction then the accepted_by_listing_creator property will be added to the transaction, and the payment for the transaction can be made.

If the listing creator rejects the transaction then the rejected_by_listing_creator property will be added to the transaction, and the status of the transaction will be updated to rejected.

This process is not necessary for face-to-face transactions because the transaction can be cancelled at any point before the final payment is made; however, this step is necessary for online transactions because the final payment is made in the first step.