Products

A product (Product) is used to group and categorize your charges (debts, subscriptions, and payment links). Its use is completely optional: you can charge without associating any product. You use it when you want to report your charges by product or service line, for example “Plan Premium”, “Gym monthly fee”, or “Internet 100MB”.

Natural key: `name`

The name is the product’s natural key and is unique per organization. Creating a product with a name that already exists does not generate a duplicate or an error: it returns the existing product.

That is why POST /products is idempotent by design: repeating the same name always returns the same product. You do not need to check beforehand whether it already exists.

Create a product

curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/products' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Plan Premium" }'

{
  "data": {
    "productId": "42",
    "name": "Plan Premium",
    "active": true,
    "createdAt": "2026-06-03T18:00:00Z",
    "updatedAt": "2026-06-03T18:00:00Z"
  },
  "requestId": "req_a1b2c3d4"
}

The productId is the identifier in the system, exposed as a string without a prefix.

Inline creation (`productName`)

You do not need to create the product in advance. You can send it inline when creating a debt, subscription, or payment link with the productName field. If the name does not exist, it is created; if it already exists, it is reused without duplicating it.

curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/debts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalClientId": "CLI-00042",
    "amount": 2500.00,
    "dueDate": "2026-07-10",
    "productName": "Gym Plan"
  }'

In the charge response, the product comes embedded with four fields:

{
  "product": {
    "productId": "42",
    "name": "Gym Plan",
    "active": true,
    "createdInline": true
  }
}

The createdInline field is true if the product was created in that same request, and false if it already existed and was reused.

Activate and deactivate

boolean

default:"true"

Status of the product. An inactive product cannot be associated with new charges.

DELETE /products/{id} performs a soft delete: it sets active: false without deleting the product, so the history is preserved. Associating an inactive product with a new charge returns 422 BUSINESS_RULE_VIOLATION.

Endpoints

Method	Path	Description
`POST`	`/products`	Create a product (or return the existing one with that `name`).
`GET`	`/products/{id}`	Retrieve a product.
`GET`	`/products`	List products (filters `name`, `active`).
`PATCH`	`/products/{id}`	Update `name` or `active`.
`DELETE`	`/products/{id}`	Soft delete (sets `active: false`).

Try it in the API Reference

Explore each endpoint with its interactive playground.

Get started

Concepts

Resources

Payment portal

Webhooks

Natural key: `name`

Create a product

Inline creation (`productName`)

Activate and deactivate

Endpoints

Try it in the API Reference

​Natural key: name

​Create a product

​Inline creation (productName)

​Activate and deactivate

​Endpoints

Try it in the API Reference

Natural key: `name`

Create a product

Inline creation (`productName`)

Activate and deactivate

Endpoints