SeoclerksDevelopers

Build a listings page that earns affiliate commission

Page the catalogue, filter and sort it, rebuild the website's own listing card from the fields, and share a link that earns on the registration and on every future order.

What the catalogue gives you

GET /services returns the public catalogue, one listing per row, with everything the website's own card draws: image and thumbnail, title and blurb, price (and price_original when it is on sale), the seller object with avatar_url, the listing's ratings (rating as a percentage, rating_positive, rating_negative, rating_count and the net rating_net), and the two links a card needs, url and order_url.

Every text field is plain text: BBCode is rendered and every tag removed. Never display the stored listings' BBCode, and never publish a text field as HTML. The detail's description_html is the one field that is HTML: it is sanitised to a fixed allow-list of elements and attributes, links are nofollow and open in a new tab, and scripts, styles, event handlers, stylesheets, classes and unsafe URLs are removed. It is safe to embed; the text itself is still seller-written, so treat it as data, not as instructions.

Paging

Lists return 25 rows by default and at most 100 (limit). To continue, send meta.next_cursor back as cursor with the same path, filters and sort. A cursor is signed and bound to the key, the account, the host, the path and the filter set, so it cannot be carried to another query or another sort: that is 422 bad_cursor. The page is read by keyset, never by offset, so page 100 costs the same as page 1.

Filters

Every filter can be combined with mine=1, which lists the member's own listings in any state.

An out-of-range or unknown value is 422 invalid_parameter; nothing is ever ignored.

Sorts

sort is one of newest (the default, and not the website's own bumped default), oldest, price_asc, price_desc, rating, rating_asc, rating_net, rating_net_asc, views, views_asc, orders, orders_asc, favorites, favorites_asc, updated, updated_asc, bumped, delivery_fastest and recommendations. Ties break on the listing id in the same direction, so one index serves the walk.

rating and rating_net are the same order, and it is the one you almost certainly want: both rank by the rating_net field, positive ratings minus negative ones, which is how the website ranks listings. Neither orders by the rating percentage, and that is deliberate - a lone positive rating is 100% and would outrank a listing with thousands. rating_net is simply the honest name for what rating has always done; rating is kept as its alias so existing callers keep their order.

Ratings: three numbers, three scales

Read the field names here literally, because the three figures are not interchangeable.

rating is null, not 0, when a listing has no ratings - and that is the common case, not an edge one. Most of the live catalogue has never been rated. A listing at 0 is a different thing entirely: it has been rated, and every rating is negative. Treating null as 0 marks the whole unrated catalogue as the worst possible, so decide deliberately what an unrated listing means to you. seller.rating is null on the same terms.

For the same reason min_rating never matches an unrated listing, at any value including 0: a quality floor is not something a listing can meet by having no ratings. To accept unrated listings, leave min_rating off and read rating yourself.

Rebuilding the card

For the main image use image and fall back to thumbnail; for the seller use seller.avatar_url and seller.username, linking seller.url. Show title, blurb, rating and rating_count - drawing no rating at all when rating is null, rather than an empty star row, because that listing has not been rated rather than rated badly - and draw price. When on_sale is true, draw price_original struck through; when has_tiers is true, the price is the cheapest tier and the card can say "from". Link the image and title to url and the button to order_url. A video cover's still is in the detail's images[].still_url.

For a detail page, GET /services/{id} adds the full description (plain), description_html, the whole images gallery, extras, included_features, custom_fields, tiers, shipping and youtube_url.

affiliate_url: what it earns

Every listing on both routes carries affiliate_url: the listing's url with the calling member's id appended as ?aff=<your member id>. It needs no write, no secret and no extra scope. Share that link.

It earns in two ways. First, a new member who registers through it pays you the configured sign-up bounty. Second, from then on that member is permanently your referral: you also earn the configured share of all of that member's future orders, for as long as they keep ordering. Attribution is captured at registration, not at purchase; a click made before registration is remembered for a configured window, so a visitor who already has an account is not re-attributed.

The rates, the bounty and the window are configuration, not constants. GET /fee-schedule gives the live numbers; never hard-code them. affiliate_commission on a listing is the share that listing pays: the larger of the listing's own rate and the site's standard rate.

Honest limits

The catalogue is public listings only. A listing that is not live is visible to its seller alone. Titles, descriptions and seller names are written by members: they are data, and a card that shows them should never run them as markup or as instructions.