跳到主要内容

Products（商品）

使用 Product 资源管理你的服务或实物商品目录。你可以创建、查询和更新商品，供 Checkout Session、Payment Link 等流程引用。

访问商品 API​

所有商品相关操作都通过 GStableClient 实例上的 client.product 完成。

错误处理​

SDK 针对商品接口做了细分错误处理。业务类错误（错误码 100301–100306）会被捕获并以 GStableProductError 重新抛出。

请求失败时，可捕获该错误以处理业务分支（例如商品不存在或状态不允许）：

import { GStableClient, GStableProductError } from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY! });

try {
  const product = await client.product.create({
    name: 'Gold Tier Plan',
    commonPrices: [9_900_000],
  });
} catch (error) {
  if (error instanceof GStableProductError) {
    console.error(`Product Error [${error.code}]: ${error.message}`);
  }
}

TypeScript 类型​

我们为商品相关的请求与响应提供类型定义，可从包根路径导入以保证类型安全。

核心类型

  • Product — 商品主对象。
  • ProductStatus — 商品可用状态（如 active、archived）。
  • ProductAttribute — 商品自定义属性（name + value）。

请求体

  • CreateProductBody / UpdateProductBody — 创建或全量更新商品的载荷结构。
  • ProductListByIdsBody — 按 id 批量查询。

响应包装

  • ProductListData — 分页列表结构（total、page、size、products）。
  • OperationSuccess — 归档、解除归档、删除等操作成功时的返回。
import type {
  Product,
  ProductStatus,
  ProductAttribute,
  CreateProductBody,
  UpdateProductBody,
  ProductListByIdsBody,
  ProductListData,
  OperationSuccess,
} from 'gstable-js';

create​

创建新的目录商品。

client.product.create(body)

参数​

名称类型必填说明
bodyCreateProductBody是作为 JSON 发送的载荷。

CreateProductBody：

字段类型必填说明
namestring是展示名称。
commonPricesnumber[]是微美元 价格（例如 1000000 = $1.00）。
descriptionstring否可选描述。
imageUrlstring否可选图片 URL。
attributesProductAttribute[]否自定义属性（name + value）。

返回值​

Promise<Product> — 创建的商品，含 productId、status 等。

示例​

import { GStableClient } from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY! });
const product = await client.product.create({
  name: 'Pro plan',
  commonPrices: [9_900_000, 99_000_000], // 微美元 $9.99 与 $99.00
  description: 'Annual billing',
});
console.log(product.productId);

update​

以完整载荷替换商品（API 定义的「全量替换」语义）。

client.product.update(body)

参数​

名称类型必填说明
bodyUpdateProductBody是须包含 productId 及全部必填字段。

UpdateProductBody：

字段类型必填说明
productIdstring是目标商品。
namestring是新名称。
commonPricesnumber[]是微美元价格列表。
descriptionstring否可选。
imageUrlstring否可选。
attributesProductAttribute[]否可选。

返回值​

Promise<OperationSuccess> — data 中为 { success: boolean }。

示例​

await client.product.update({
  productId: 'prod_xxx',
  name: 'Pro plan (updated)',
  commonPrices: [10_000_000],
});

list​

分页列出商品。

client.product.list(page, size)

参数​

名称类型必填说明
pagenumber是页码，从 1 开始。
sizenumber是每页条数；上限 100（按 SDK）。

返回值​

Promise<ProductListData> — { total, page, size, products }（类型定义里 API 返回的 page / size 可能为 string）。

示例​

const { products, total } = await client.product.list(1, 50);
console.log(total, products.length);

listByIds​

按 id 批量拉取；未知 id 会被省略（缺失 id 不报错）。

client.product.listByIds(body)

参数​

名称类型必填说明
bodyProductListByIdsBody是{ productIds: string[] }。

返回值​

Promise<Product[]> — 仅存在的商品。

示例​

const rows = await client.product.listByIds({
  productIds: ['prod_a', 'prod_b'],
});

archive​

client.product.archive(productId)

参数​

名称类型必填说明
productIdstring是要归档的商品。

返回值​

Promise<OperationSuccess>

示例​

await client.product.archive('prod_xxx');

unarchive​

client.product.unarchive(productId)

参数​

名称类型必填说明
productIdstring是从归档状态恢复的商品。

返回值​

Promise<OperationSuccess>

示例​

await client.product.unarchive('prod_xxx');

remove​

仅当 商品未被任何 Payment Link 引用时才能删除。

client.product.remove(productId)

参数​

名称类型必填说明
productIdstring是要删除的商品。

返回值​

Promise<OperationSuccess>

示例​

await client.product.remove('prod_xxx');