Products API

This is a console-managed endpoint family for merchant catalog operations. The public merchant API uses x-api-key; these /api/console/* routes use Privy Bearer tokens and are dashboard-only.

Manage your product catalog. Products represent items you sell — each has a fixed price, name, and optional image. Attach a product to a Payment Link to auto-populate the checkout page, or mark it as a recurring subscription so Coal can create subscription records and renewal checkout cycles automatically.

The Product Object

json

1{
2  "id": "clxxx123",
3  "merchantId": "clmerchant456",
4  "name": "Pro Plan",
5  "description": "Unlimited API calls, priority support, and advanced analytics.",
6  "price": "49.99",
7  "image": "https://cdn.yoursite.com/pro-plan.png",
8  "sku": "PRO-MONTHLY",
9  "billingType": "subscription",
10  "billingInterval": "month",
11  "billingIntervalCount": 1,
12  "active": true,
13  "createdAt": "2026-01-15T10:00:00.000Z",
14  "updatedAt": "2026-03-22T08:30:00.000Z"
15}

Field	Type	Description
`id`	string	Unique product ID (CUID)
`merchantId`	string	ID of the owning merchant
`name`	string	Display name shown on checkout
`description`	string \| null	Optional description
`price`	string	Price in the merchant's settlement currency (decimal string)
`image`	string \| null	URL of product image
`sku`	string \| null	Your internal SKU for inventory sync
`billingType`	`one_time` \| `subscription`	Whether this product is sold once or on a recurring cadence
`billingInterval`	`day` \| `week` \| `month` \| `year` \| null	Required when `billingType` is `subscription`
`billingIntervalCount`	number	Repeat multiplier for recurring products
`active`	boolean	`false` = hidden from payment links
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modified timestamp

List Products

GET/api/console/products

Returns all products for the authenticated merchant, ordered by creation date descending.

Authentication: Authorization: Bearer <Privy JWT>

bash

1curl https://api.usecoal.xyz/api/console/products \
2  -H "Authorization: Bearer <Privy JWT>"

json

1{
2  "data": {
3    "products": [
4      {
5        "id": "clxxx123",
6        "name": "Pro Plan",
7        "price": "49.99",
8        "image": "https://cdn.yoursite.com/pro.png",
9        "active": true,
10        "createdAt": "2026-01-15T10:00:00.000Z"
11      }
12    ]
13  }
14}

Create a Product

POST/api/console/products

Authentication: Authorization: Bearer <Privy JWT>

Request body:

Parameter	Type	Required	Description
`name`	string	required	Product display name (shown on checkout page)
`price`	number \| string	required	Price in the merchant's settlement currency. Accepts decimal up to 6 places.
`description`	string	optional	Optional description displayed under the product name
`image`	string (URL)	optional	Publicly accessible image URL. Shown on the checkout page.
`sku`	string	optional	Your internal SKU for inventory management
`billingType`	"one_time" \| "subscription"	optional	Set to `subscription` to create a recurring product.
`billingInterval`	"day" \| "week" \| "month" \| "year"	optional	Required for subscription products.
`billingIntervalCount`	number	optional	How often the subscription renews. Defaults to 1.

bash

1curl -X POST https://api.usecoal.xyz/api/console/products \
2  -H "Authorization: Bearer <Privy JWT>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Pro Plan",
6    "description": "Unlimited API calls and priority support.",
7    "price": 49.99,
8    "image": "https://cdn.yoursite.com/pro.png",
9    "sku": "PRO-MONTHLY",
10    "billingType": "subscription",
11    "billingInterval": "month",
12    "billingIntervalCount": 1
13  }'

json

1{
2  "data": {
3    "id": "clxxx123",
4    "name": "Pro Plan",
5    "price": "49.99",
6    "active": true,
7    "createdAt": "2026-03-22T12:00:00.000Z"
8  }
9}

Update a Product

PUT/api/console/products/:id

All fields are optional — only include the ones you want to change.

bash

1curl -X PUT https://api.usecoal.xyz/api/console/products/clxxx123 \
2  -H "Authorization: Bearer <Privy JWT>" \
3  -H "Content-Type: application/json" \
4  -d '{ "price": 59.99, "description": "Now includes dedicated support." }'

json

1{
2  "data": {
3    "id": "clxxx123",
4    "name": "Pro Plan",
5    "price": "59.99",
6    "updatedAt": "2026-03-22T13:00:00.000Z"
7  }
8}

Delete a Product

DELETE/api/console/products/:id

Permanently deletes the product. Any payment links attached to this product will become inactive.

bash

1curl -X DELETE https://api.usecoal.xyz/api/console/products/clxxx123 \
2  -H "Authorization: Bearer <Privy JWT>"

json

1{
2  "data": { "success": true }
3}

Error Codes

Code	HTTP	Description
`UNAUTHORIZED`	401	Missing or invalid Privy JWT
`NOT_FOUND`	404	Product does not exist or belongs to another merchant
`VALIDATION_ERROR`	400	Invalid field values (see `details`)