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 (cards table)" in the backend. After a successful payment, the fulfillment engine automatically extracts a key record with isUsed = false from 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 processing after 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 delivered status, 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 isPlan field has been deprecated and is now completely taken over by type='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 in metaData, 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:
    1. During checkout, the frontend automatically renders input fields based on form_schema for the buyer to fill out.
    2. After payment, the order status enters processing.
    3. 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 delivered and can add delivery remarks to feedback to the buyer.

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 Quota granted per purchase.
  • Fulfillment: After payment, the system automatically generates a unique sk_... secret key via underlying encryption algorithms, writes it to the api_keys asset 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:

  1. Add an enum to products.type in schema.ts.
  2. Add the corresponding switch case fulfillment logic in server/utils/fulfillment.ts. There is absolutely no need to modify the core payment flow.