Product Types & Fulfillment Mechanism
APayShop is a full-scenario virtual trading engine. To meet the selling needs of different digital nomads, the system reuses the same products database table at the bottom level. Through the core field type combined with the metaData JSON extension, it implements 5 distinct product types and automatic fulfillment mechanisms.
All fulfillment (delivery) logic is unified and abstracted in the backend server/utils/fulfillment.ts engine.
1. Key (key)
Suitable for: Game time cards, software activation codes, account passwords.
- Mechanism: The product needs to be associated with a "Key Pool (
cardstable)" in the backend. After a successful payment, the fulfillment engine automatically extracts a key record withisUsed = falsefrom the corresponding pool, marks it as used, and displays it to the buyer. - Out of Stock Handling: If the key pool is out of stock (Sold Out), users can still place an order (unless anti-oversell limits are enabled), but the order status will enter
processingafter payment, prompting the administrator to manually restock.
2. Digital File (file)
Suitable for: PDF e-books, cloud drive links, video tutorial archives.
- Mechanism: When creating a product, the administrator configures a fixed or dynamic file download link (Resource URL) or cloud drive extraction code in
metaData. - Fulfillment: After successful payment, the order immediately changes to
deliveredstatus, and these hidden download links are displayed directly in the "Fulfillment Result" section of the order details page.
3. Subscription (subscription)
Suitable for: SaaS monthly memberships, paid community access.
- Mechanism: This type of product represents an ongoing service status. The original
isPlanfield has been deprecated and is now completely taken over bytype='subscription'. - Fulfillment: After purchase, the order status directly changes to
active. The valid period of the subscription (e.g.,1_month,1_year,lifetime) is recorded inmetaData, making it easy for third-party systems or administrators to determine if the user's rights have expired.
4. Manual Service / Top-up (service)
Suitable for: Game boosting, server setup, non-standard services requiring buyer customization.
- Mechanism: This type relies on a powerful Dynamic Form Engine. When configuring the product in the backend, the administrator defines a JSON array in
metaData.form_schema(e.g., requiring the buyer to input game server, character ID, server IP, etc.). - Fulfillment:
- During checkout, the frontend automatically renders input fields based on
form_schemafor the buyer to fill out. - After payment, the order status enters
processing. - The administrator sees the form data filled by the user in the backend order list. After performing manual delivery/top-up, they manually change the order status to
deliveredand can add delivery remarks to feedback to the buyer.
- During checkout, the frontend automatically renders input fields based on
5. Dynamic API Quota (dynamic_api)
Suitable for: AI interface aggregation sales, data query API call limit sales.
- Mechanism: Designed specifically for geek developers. When configuring the product, the administrator can set the
Quotagranted per purchase. - Fulfillment: After payment, the system automatically generates a unique
sk_...secret key via underlying encryption algorithms, writes it to theapi_keysasset table, and allocates the purchased quota. Users can immediately copy this API Key from the order and place it in the Authorization header of their code to call your system API.
💡 Developer Tip
If you are doing secondary development based on APayShop and need to add a brand new sales type (such as offline electronic ticket verification
event), you only need to:
- Add an enum to
products.typeinschema.ts.- Add the corresponding
switch casefulfillment logic inserver/utils/fulfillment.ts. There is absolutely no need to modify the core payment flow.