The HstockPlus Platform: How Orders, Fulfilment and the API Actually Fit Together

This page describes how the marketplace works as a system: the roles it has, the path an order takes, and what the API exposes. Nothing is sold from this page.

Two catalogues, not one

The platform carries two kinds of stock and they behave differently enough that treating them as one thing causes problems.

Product listings are digital goods sold as units from a seller's inventory: accounts, mailboxes, proxies, keys. Roughly seventeen thousand are visible to buyers at any time, drawn from a larger catalogue that includes drafts, listings awaiting approval and listings a seller has switched off. They are grouped into categories and subcategories, tagged for filtering, and priced per variant rather than per listing, so a single listing can carry several purchasable options at different prices.

Growth services are quantity-based: you order a number of followers, views or comments against a link. Around thirty thousand are live. They use their own categorisation and their own tag vocabulary, and they are not counted against a seller's product listing limit.

Sellers number in the low hundreds by active catalogue, against about fifteen hundred accounts holding the seller role, spread across roughly five hundred and sixty shops.

Roles and what each one can reach

Three roles exist and they are additive rather than exclusive, so one account can be both a buyer and a seller.

• Buyers browse, order, hold a site balance, track orders and open support tickets.
• Sellers manage listings and inventory, process orders, configure coupons, and request payouts. A seller profile can be made publicly visible so buyers can browse everything that seller offers in one place.
• Administrators approve sellers and listings, resolve disputes, and hold the settings that most of the platform's behaviour reads from.

Seller approval is currently required, and it gates the API as well as the interface: a seller whose account has not been approved receives an explicit pending-approval response rather than an empty catalogue, which is a useful thing to distinguish when an integration returns nothing.

Sellers sit on one of five tiers derived from rolling twelve-month attributed sales. The tier is not decorative. It sets how long the platform waits before releasing funds automatically, and it feeds the listing limit calculation.

How an order moves

Order state and payment state are tracked separately, and both matter when you are reading the API.

An order's own state runs through pending, processing, completed, and then possibly refunded, with cancelled and error as terminal edges. Payment state is a separate field with its own values: completed, partial, refunded, failed, pending and processing. One thing to note if you are writing a filter: there is no "paid" payment state. A query for one returns nothing, which reads like an empty result rather than a mistake in the query.

Fulfilment differs by listing type. Automatic and inventory-backed listings hand over stock the platform already holds. Manual listings are the ones that need a seller or a seller's software to act, and those are what the fulfilment API is for.

Once a buyer has what they ordered, a warranty window opens. It is measured in hours and it runs from delivery rather than from payment, with a site-wide floor of a few hours and per-seller settings above it. Within that window a buyer can open a ticket or a dispute; outside it, the dispute route refuses. Funds release to the seller either when the buyer confirms or when the auto-confirm timer for that seller's tier expires, whichever comes first, and a live dispute holds the release.

The API, and the one distinction that matters most

There are two API surfaces, both authenticated by key.

The buyer-facing surface follows the widely used panel convention: a single endpoint taking an action parameter. The standard actions are all implemented, so existing panel tooling works against it: services to list what is available, add to place an order, status to check one, balance, refill and cancel. On top of those it adds actions the convention does not define: categories and subcategory_info for navigating the taxonomy, products and shops, allowcancel, inventory for stock checks, and a full set of SMS verification actions covering projects, countries, ordering a number, and polling for the code. Treat it as the standard convention plus extensions, rather than as a drop-in clone; the standard calls will work unchanged, and the extensions are where the platform-specific capability lives.

The seller-facing surface is a conventional REST API covering products, orders, tickets and payments. Within it there is one distinction that decides whether your integration is correct, and it is easy to get wrong because both endpoints return orders.

• Listing orders is a read. It claims nothing. Two workers polling it both receive the same order, and both will try to deliver it.
• Pulling orders is a claim. It moves each order from pending to processing with a conditional write, and returns only the orders whose write actually won. If two workers pull simultaneously, each receives a disjoint set.

Anything that fulfils automatically should pull, not list. Use the read for dashboards and reconciliation, where seeing the same order twice is harmless.

Three further details save an afternoon. Pulling returns manual-fulfilment lines only, so automatic and inventory-backed stock will never appear there. The default batch is a hundred orders and the ceiling is five hundred. And a pulled order is not offered again for about half an hour, which is a deliberate safety margin: if your worker crashes after pulling, the order comes back on its own, but not instantly.

Full reference for both surfaces lives at the buyer API documentation and the seller API documentation.

Payments and balances

The platform runs an internal balance that most activity flows through. Buyers top it up and spend from it, refunds are credited to it, and it is where the majority of orders are actually paid from. Both cryptocurrency and conventional payment channels are supported for topping up, some settling directly and others through a payment processor.

Sellers request payouts against settled, released order value. A minimum applies, set platform-wide with additional per-method minimums on top, and payouts carry a percentage fee. There is no per-order commission taken from sellers, so the payout fee is where the platform's cut sits rather than in the sale itself.

Support and disputes

Support runs through a ticket system shared by all three roles, so a buyer, a seller and support can be in one thread rather than in three conversations that never meet. Tickets carry a problem classification, and a seller can resolve one by replacing the delivered item, refunding it, or rejecting the claim.

Disputes are the heavier route and are deliberately narrower: they require the order to be complete and inside its warranty window, at least one screenshot, and a selection from a two-level problem list. They end in the funds going to the seller or back to the buyer. A replacement is not a dispute outcome, which is why the ticket route resolves the large majority of real problems and why opening a ticket first is usually the faster path.

What runs on a schedule

Several things happen without anyone triggering them, and an integration is easier to reason about knowing they exist: funds auto-confirm and release after the seller's tier delay; a dispute left alone after all its tickets are closed resolves in the seller's favour after a fixed number of days; featured placements expire on a daily job; approved promotional shares are re-checked weekly; and listing text is scanned in batches against the platform's off-platform contact rules.

None of these announces itself to the API. If your reconciliation sees an order change state with no call from you, one of them is usually why.

Getting started

1. Register, then request seller approval if you intend to sell. Approval gates the API as well as the interface.
2. Create listings, or import growth services from a configured upstream provider in bulk rather than one at a time.
3. Generate an API key and confirm your role by calling the profile endpoint before anything else.
4. If you fulfil manually, build against the pull endpoint from the start. Switching from list to pull after you have shipped duplicate deliveries is a worse day than reading this paragraph.
5. Set warranty hours per listing deliberately. It is the clock every buyer protection on the platform runs against, and it starts at delivery.