Product

The Product object is the basic inventory unit in the GStable system.

When using Payment Link (No-Code Mode), you must create a product first, as a Payment Link essentially points to one or more products. When using Checkout Session (Low-Code Mode), products are optional; you can choose to pass an existing productId or define disposable line items directly in the Session.

Product Object

Core Attributes

Attribute	Type	Description
productId	String	Unique identifier for the product (e.g., prd_TLEGL1FK...).
name	String	Product name.
description	String	Product description.
imageUrl	String	URL of the product image. GStable will automatically download and host this image.
status	String	Status. active or archived.
commonPrices	Array	List of common prices (Unit: Micro-USD).
attributes	Array	List of custom attributes (e.g., Size, Color).

Price Unit Explanation (Micro-USD)

GStable unifies product prices using Micro-USD (one-millionth of a US Dollar) as integers to avoid floating-point precision issues.

• 1000000 = $1.00 USD
• 2000000 = $2.00 USD

---

Create Product

When creating a product, you can provide an external image link. GStable will automatically download and re-upload it to its internal file service to ensure loading speed and stability at the checkout.

POST /product/create

Request Parameters

Parameter	Type	Required	Description
name	String	✅	Product name (Max 100 chars).
commonPrices	Integer[]	✅	List of Common Prices. Min 1, Max 5. Used for quick pricing selection when creating Payment Links in the Dashboard.
description	String	❌	Product description (Max 1000 chars).
imageUrl	String	❌	Must be an HTTPS URL (Max 500 chars). System will auto-save it. If download fails, the product will still be created but the image won't display.
attributes	Object[]	❌	Product attributes (Max 10). Contains name and value.

Request Example

{
  "name": "Premium Membership",
  "description": "Unlock all premium features",
  "imageUrl": "https://yoursite.com/product_01.png",
  "attributes": [
    { "name": "Duration", "value": "1 Month" },
    { "name": "Level", "value": "VIP" }
  ],
  "commonPrices": [1000000, 2000000, 5000000]
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "productId": "prd_TLEGL1FKzZt9hqWu",
    "name": "Premium Membership",
    "description": "Unlock all premium features",
    "imageUrl": "https://files.gstable.io/product/prd_TLEGL1FKzZt9hqWu/image.png", // Note: This is the hosted URL
    "status": "active",
    "attributes": [
      { "name": "Duration", "value": "1 Month" },
      { "name": "Level", "value": "VIP" }
    ],
    "commonPrices": [1000000, 2000000, 5000000]
  }
}

---

Update Product

POST /product/update

Full Replacement

The update interface adopts a Full Replacement strategy. When calling this interface, you must pass all fields of the product (including those you do not want to modify). Optional fields not included in the request may be reset.

Special Behavior

• Image Update: If you provide a new imageUrl, the system will re-download and overwrite the old image. The interface response does not contain the new image URL, but subsequent queries will return the updated address.

Request Example

{
  "productId": "prd_TLEGL1FKzZt9hqWu", // Required
  "name": "Premium Membership (Updated)",
  "description": "Unlock all premium features",
  "imageUrl": "https://example.com/new-image.png",
  "attributes": [
    { "name": "Duration", "value": "1 Month" }
  ],
  "commonPrices": [1000000]
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

Get Product List

GET /product/list/:page/:size

This interface supports pagination. Pagination parameters are passed directly via the URL path.

• page: Page number, starting from 1.
• size: Items per page, max 100.

Request Example

GET /product/list/1/10

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 6,
    "page": "1",
    "size": "10",
    "products": [
      {
        "productId": "prd_6syzYz_j4WRqs-jOaji6SA",
        "name": "Premium Membership",
        "status": "active",
        "createAt": "2025-12-25 01:58:29",
        ...
      }
    ]
  }
}

---

Batch Get Products

POST /product/list/by/ids

This interface is often used with creating Payment Links. If you have a set of IDs and want to verify their existence and get detailed information, use this interface.

• If the requested IDs contain non-existent products, the response list will only return the existing ones and will not report an error.

Request Example

{
  "productIds": [
    "prd_6syzYz_j4WRqs-jOaji6SA",
    "prd_invalid_id_example"
  ]
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "productId": "prd_6syzYz_j4WRqs-jOaji6SA",
      "name": "Premium Membership",
      ...
    }
    // Note: prd_invalid_id_example is not returned
  ]
}

---

Archive & Unarchive

Manage the lifecycle status of products.

Cascading Disable Logic

Archiving has a cascading effect:

1. When Archiving: Once a product is archived, all Payment Links associated with that product will be automatically Disabled. This prevents users from paying for discontinued products.
2. When Unarchiving: After a product is restored to active status, associated Payment Links will not automatically recover. You need to manually Enable the corresponding Payment Links via API or Dashboard.

Archive

POST /product/archive

Unarchive

POST /product/unarchive

Request Example

{
  "productId": "prd_TLEGL1FKzZt9hqWu"
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

Remove Product

POST /product/remove

Deletion operations have strict business restrictions to ensure the integrity of historical data.

Deletion Restrictions

• Unused: Only products that have never been associated with any Payment Link can be deleted.
• Used: Once a product has been referenced by any Payment Link (including disabled or deleted Links), the product cannot be permanently deleted. For such products, it is recommended to use the Archive function.

Request Example

{
  "productId": "prd_TLEGL1FKzZt9hqWu"
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}