Products

Use the Product resource to manage your service or goods catalog. You can create, retrieve, and update products for use in Checkout Sessions, Payment Links, and related flows.

Accessing products

All product operations are available via the client.product property on your GStableClient instance.

Error handling

The SDK provides granular error handling for product operations. Business-specific errors (error codes 100301–100306) are captured and re-thrown as GStableProductError.

When a request fails, you can catch this error to branch on product-specific failures (for example, product not found or invalid status):

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 support

We provide TypeScript definitions for product payloads and responses. Import them from the package root for type-safe calls.

Core types

• Product — The main product object.
• ProductStatus — Product availability (for example, active or archived).
• ProductAttribute — Custom attributes (name + value) on a product.

Request bodies

• CreateProductBody / UpdateProductBody — Schemas for creating or fully replacing a product.
• ProductListByIdsBody — Batch retrieval by product id.

Response wrappers

• ProductListData — Paginated list shape (total, page, size, products).
• OperationSuccess — Returned for successful archive, unarchive, remove, and similar operations.

import type {
  Product,
  ProductStatus,
  ProductAttribute,
  CreateProductBody,
  UpdateProductBody,
  ProductListByIdsBody,
  ProductListData,
  OperationSuccess,
} from 'gstable-js';

---

create

Creates a new catalog product.

client.product.create(body)

Parameters

Name	Type	Required	Description
body	CreateProductBody	Yes	Payload sent as JSON.

CreateProductBody:

Field	Type	Required	Description
name	string	Yes	Display name.
commonPrices	number[]	Yes	Prices in micro-USD (e.g. 1000000 = $1.00).
description	string	No	Optional description.
imageUrl	string	No	Optional image URL.
attributes	ProductAttribute[]	No	Custom attributes (name + value).

Returns

Promise<Product> — Created product, including productId, status, etc.

Example

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 and $99.00 in micro-USD
  description: 'Annual billing',
});
console.log(product.productId);

---

update

Replaces a product with a full payload (API-defined “full replace” semantics).

client.product.update(body)

Parameters

Name	Type	Required	Description
body	UpdateProductBody	Yes	Must include productId and all required fields.

UpdateProductBody:

Field	Type	Required	Description
productId	string	Yes	Target product.
name	string	Yes	New name.
commonPrices	number[]	Yes	Micro-USD price list.
description	string	No	Optional.
imageUrl	string	No	Optional.
attributes	ProductAttribute[]	No	Optional.

Returns

Promise<OperationSuccess> — { success: boolean } in data.

Example

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

---

list

Paginated product listing.

client.product.list(page, size)

Parameters

Name	Type	Required	Description
page	number	Yes	Page index, starts at 1.
size	number	Yes	Page size; maximum 100 (per SDK).

Returns

Promise<ProductListData> — { total, page, size, products } (page / size are string in the type definition as returned by the API).

Example

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

---

listByIds

Batch fetch by id; unknown ids are omitted (no error for missing ids).

client.product.listByIds(body)

Parameters

Name	Type	Required	Description
body	ProductListByIdsBody	Yes	{ productIds: string[] }.

Returns

Promise<Product[]> — Only products that exist.

Example

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

---

archive

client.product.archive(productId)

Parameters

Name	Type	Required	Description
productId	string	Yes	Product to archive.

Returns

Promise<OperationSuccess>

Example

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

---

unarchive

client.product.unarchive(productId)

Parameters

Name	Type	Required	Description
productId	string	Yes	Product to restore from archived state.

Returns

Promise<OperationSuccess>

Example

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

---

remove

Deletes a product only if it is not referenced by any Payment Link.

client.product.remove(productId)

Parameters

Name	Type	Required	Description
productId	string	Yes	Product to delete.

Returns

Promise<OperationSuccess>

Example

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