Products

Product objects represent the goods or services you sell. By attaching a Product to a CheckoutSession, a PaymentLink, or an Invoice, you display the product’s details on the payment page and in receipts.

Each Product carries its own price (unit_amount + currency). For variable-priced products or open donations, use price_type: “free”.

Products vs. a direct amount

You can create a PaymentIntent with a raw amount without a Product. Products are recommended as soon as you want to display a name, description, and image on the payment page, or generate per-product reports in your dashboard.

Endpoints

Méthode	Endpoint	Description
POST	`/products/`	Create a product
GET	`/products/`	List products (paginated, filterable)
GET	`/products/{id}/`	Retrieve a product by its ID
PATCH	`/products/{id}/`	Update a product
DELETE	`/products/{id}/`	Archive a product (soft delete)

Is this introduction helpful?

Object schema

ResponseProduct object

Full structure returned by all endpoints of this resource.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "app": "app_xxxxxxxx",
  "name": "Advanced Excel Training",
  "description": "Master Excel for your business",
  "images": [
    "https://cdn.sangho.ga/products/excel.jpg"
  ],
  "unit_amount": 25000,
  "currency": "XAF",
  "price_type": "fixed",
  "active": true,
  "metadata": {
    "sku": "FORM-XLS-001",
    "category": "training"
  },
  "livemode": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Create a Product

Creates a new product in your catalog. The product is immediately available to be attached to a CheckoutSession, PaymentLink, or Invoice.

POSTRequest body

nameRequis

stringex :Advanced Excel Training

Name of the product. Visible to the buyer on the payment page, in receipts, and in confirmation emails.

Max 255 characters. Choose a clear, descriptive name — it’s the first piece of information the buyer sees before paying.

unit_amountRequis

integercentsex :25000

Unit price in cents. Ignored if price_type is free.

Same rule as for PaymentIntents: always express in cents. 25,000 XAF = 25000. For decimal currencies (USD, EUR), 25 USD = 2500.

currencyRequis

stringISO 4217ex :XAF

ISO 4217 currency code for the product. Must match a currency enabled on your App.

price_typeRequis

stringdéfaut :fixed

Determines whether the price is fixed or open. Values: fixed (price set by unit_amount) or free (the buyer enters the amount).

free is ideal for donations, crowdfunding, or “pay what you want” payments. In this mode, unit_amount can serve as a suggested amount displayed to the buyer.

descriptionOptionnel

string

Detailed description of the product. Displayed below the name on the payment page and in receipts.

Max 2,000 characters. Plain text only — no HTML. A good description increases buyer confidence and reduces payment abandonment.

imagesOptionnel

array[url]

List of product image URLs. The first image is used as the main image on the payment page.

Maximum 8 images. Accepted formats: JPEG, PNG, WebP. Recommended dimensions: 800×800 px minimum. URLs must be publicly accessible (HTTPS). Sangho does not store images — reference your own CDN URLs.

activeOptionnel

booleandéfaut :true

Indicates whether the product is active and can be used in new CheckoutSessions, PaymentLinks, or Invoices.

Deactivating a product (active: false) does not delete existing links — payments in progress remain valid. It’s a way to remove a product from the catalog without losing history.

metadataOptionnel

object

Free-form data associated with the product — internal SKU, category, ERP reference, etc.

The Product’s metadata is included in the checkout.completed and payment_intent.succeeded webhooks when a Product is attached. Useful for triggering server-side automations (license delivery, access activation, etc.).

Are the creation parameters clear?

Create a Product

bash

curl -X POST https://api.sangho.ga/v1/products/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Excel Training",
    "description": "Master Excel for your business",
    "unit_amount": 25000,
    "currency": "XAF",
    "price_type": "fixed",
    "images": ["https://cdn.exemple.com/excel.jpg"],
    "metadata": { "sku": "FORM-XLS-001" }
  }'

Response201 Created

The product is created and immediately available to be attached to a CheckoutSession or PaymentLink.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "name": "Advanced Excel Training",
  "description": "Master Excel for your business",
  "images": ["https://cdn.exemple.com/excel.jpg"],
  "unit_amount": 25000,
  "currency": "XAF",
  "price_type": "fixed",
  "active": true,
  "metadata": { "sku": "FORM-XLS-001" },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

List Products

GETQuery parameters

activeOptionnel

boolean

Filter by activation status. true returns only active products, false returns archived ones.

By default (without this filter), all active AND archived products are returned. Use active=true to show only the current catalog to your customers.

currencyOptionnel

stringISO 4217

Filter by currency. Useful if your catalog covers multiple markets with different currencies.

searchOptionnel

string

Search on the product’s name and description. Partial match, case-insensitive.

orderingOptionnel

stringdéfaut :-created_at

Sorting. Available fields: created_at, name, unit_amount.

pageOptionnel

integerdéfaut :1

Page number.

page_sizeOptionnel

integerdéfaut :20

Results per page. Maximum: 100.

Update a Product

Updates the fields of an existing Product. Changing the price ( unit_amount) does not affect CheckoutSessions or PaymentLinks already created — only new ones use the new price.

PATCHUpdate body (PATCH)

nameOptionnel

string

New name. Updated on the payment page for existing links not yet paid.

unit_amountOptionnel

integercents

New unit price.

Changing a product’s price does not retroactively affect payment sessions already created. Only new CheckoutSessions created after the change will use the new price.

activeOptionnel

boolean

Activate (true) or archive (false) the product.

metadataOptionnel

object

Merged with existing metadata.

Archive a Product

The DELETE endpoint archives the product (soft delete) by setting active to false. The product remains accessible via the API but can no longer be attached to new links.

Soft delete, not an actual deletion

Unlike Customers, deleting a Product is reversible. You can reactivate it via PATCH { active: true }. Existing PaymentLinks and CheckoutSessions that reference this product continue to work.

Are the operations on Products well documented?

List active products

bash

curl "https://api.sangho.ga/v1/products/?active=true&currency=XAF" \
  -H "Authorization: Bearer sk_prod_xxxx"

Update a product

bash

curl -X PATCH https://api.sangho.ga/v1/products/prod_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_amount": 30000,
    "metadata": { "sku": "FORM-XLS-002", "promotion": null }
  }'

Response200 OK — Product updated

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "name": "Advanced Excel Training",
  "unit_amount": 30000,
  "currency": "XAF",
  "active": true,
  "metadata": { "sku": "FORM-XLS-002" },
  "updated_at": "2026-03-15T09:00:00Z"
}

Archive a product

bash

curl -X DELETE https://api.sangho.ga/v1/products/prod_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response200 OK — Archived

The product is archived (active: false). It remains readable but can no longer be attached to new links.

Deleting a Product is reversible via PATCH { active: true }. Existing PaymentLinks continue to work.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "active": false,
  "updated_at": "2026-03-20T12:00:00Z"
}