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 company. If an active product with that name already exists, POST /products answers 201 with the existing product, unchanged: it does not generate a duplicate or an error.

That is why POST /products is idempotent by design: repeating the same name returns the same product, as it is stored (any other values you send in the body are ignored). The exception is externalProductId: if the existing product already has a different externalProductId, the API answers 409 RESOURCE_CONFLICT.

Create a product

curl --request POST \
  --url 'https://tapipay-facade.homo.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", "externalProductId": "PLAN-PREMIUM" }'

{
  "data": {
    "productId": "prd_42",
    "name": "Plan Premium",
    "externalProductId": "PLAN-PREMIUM",
    "active": true,
    "createdAt": "2026-06-03T18:00:00.000Z",
    "updatedAt": "2026-06-03T18:00:00.000Z"
  },
  "requestId": "req_a1b2c3d4"
}

The response reflects what was stored (timestamps, externalProductId, and active), not the request.

The productId is the product’s public ID, with the prd_ prefix (e.g. prd_12985). In the path of GET, PATCH, and DELETE /products/{id} the number without prefix (12985) is also accepted; other prefixes or non-numeric values return 404 RESOURCE_NOT_FOUND.

string

Your own identifier for the product (optional). It is what you later use to reference it when creating debts, without having to store Tapi’s productId. It does not accept the characters ', ", \, or ; (returns 400).

Validations

name and externalProductId are trimmed before being stored.
Fields not declared in the body are ignored.
If the externalProductId is already used by another product, or the name already exists with a different externalProductId, the API answers 409 RESOURCE_CONFLICT (with the same message in both cases).

Clients with several companies

If your TapiPay client has a single company, there is nothing to indicate: everything you create belongs to it. If your client manages several companies (for example, a network of schools where each school is a Tapi company), tell us which one the product belongs to with companyCode in the body:

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/products' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Tuition", "externalProductId": "TUITION-SCHOOL-01", "companyCode": "MX-S-04937" }'

The product is created inside that company: name and externalProductId are unique per company, so the same name can exist in each of your companies without conflict. To list the products of one company use GET /products?companyCode=MX-S-04937.

string

Tapi company (MX-S-…) the product is created in. Optional if your client has a single company. It must belong to your client.

Situation	Response
Your client has several companies and you omit `companyCode`	`400 BAD_REQUEST`: the API asks for the `companyCode`
You send a `companyCode` that does not belong to your client	`422 RESOLUTION_ERROR`
Your client has a single company and you send a different one	`422 RESOLUTION_ERROR`

This rule applies to the whole API, not just products: a client with several companies sends companyCode on every request (in the body for POST/PATCH, or as ?companyCode= for GET). In a PATCH, the companyCode in the body is taken as context, not as a field to modify. See API conventions. When creating debts with POST /v2/debts, the product is looked up inside the request’s company: a product from one company cannot be used in a debt of another.

Referencing a product in a debt

When creating a debt with POST /v2/debts, the product must already exist and is referenced by productId (format prd_<number>; any other format returns 400 INVALID_REQUEST) or externalProductId (only one; sending both returns 400). The debts endpoint does not create products: sending productName returns 400 INVALID_REQUEST, and referencing a nonexistent product returns 404 RESOURCE_NOT_FOUND without creating the debt.

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/v2/debts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Idempotency-Key: INV-2026-001' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalClientId": "CLI-00042",
    "externalProductId": "PLAN-PREMIUM",
    "amount": 2500.00,
    "dueDate": "2026-07-10"
  }'

In the debt response, the product comes embedded:

{
  "product": {
    "productId": "prd_42",
    "name": "Plan Premium",
    "active": true,
    "createdInline": false
  }
}

Referencing a product is what enables direct debit for that debt.

Inline creation (`productName`)

In subscriptions and payment links you can send the product inline with the productName field: if the name does not exist, it is created; if it already exists, it is reused without duplicating it.

This does not apply to debts. POST /v2/debts does not accept productName (it returns 400 INVALID_REQUEST) and never creates products: see Referencing a product in a debt.

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/subscriptions' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalSubscriptionId": "SUB-2026-007",
    "externalClientId": "CLI-00042",
    "amount": 999.00,
    "intervalUnit": "month",
    "intervalCount": 1,
    "startDate": "2026-06-15",
    "productName": "Gym Plan"
  }'

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

{
  "product": {
    "productId": "prd_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. For debts it is always false.

List products

GET /products returns only active products, sorted by productId descending.

Filter	Behavior
`name`	Contains, case-insensitive.
`externalProductId`	Exact match.
`active`	Only accepts `true` or `false` (any other value returns `400`). Since the list only includes active products, `active=false` always returns an empty list.
`companyCode`	Company whose products are listed (only if your client has several).

Pagination uses page (default 1) and limit (default 50, maximum 500). See API conventions.

Update

PATCH /products/{id} accepts only two fields:

string

New name, non-empty string. If another product already uses it, even an inactive one, returns 409 RESOURCE_CONFLICT.

boolean

Only true or false. active: false deactivates the product just like DELETE. active: true changes nothing: a product you can read is already active, and an inactive one returns 404. It is accepted so you can send the full object.

An empty body, or any other field, returns 400 INVALID_REQUEST. Invalid types (for example "active": "no") return 400 with the detail in details[]. The companyCode in the body is taken as context, not as a field to modify.

Known limitation: updatedAt does not reflect changes made with PATCH.

Deactivate

boolean

default:"true"

Status of the product.

DELETE /products/{id} performs a soft delete: it sets active: false without deleting the product, so the history is preserved. A DELETE on an already deleted product returns 404 RESOURCE_NOT_FOUND.

An inactive product (deleted, deactivated with PATCH, or created with active: false) is out of reach of the API:

It does not appear in GET /products, and GET /products/{id} returns 404.
It cannot be reactivated through the API: a PATCH with active: true also returns 404.
It cannot be used in new debts, payment links, or subscriptions.
Its name stays taken: another product cannot be renamed to that name (409 RESOURCE_CONFLICT).

Creating a product with active: false returns the product with active: false and createdAt/updatedAt set to null.

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 active products (filters `name`, `externalProductId`, `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

What's new

Concepts

Resources

Payment portal

Webhooks

Natural key: `name`

Create a product

Validations

Clients with several companies

Referencing a product in a debt

Inline creation (`productName`)

List products

Update

Deactivate

Endpoints

Try it in the API Reference

​Natural key: name

​Create a product

​Validations

​Clients with several companies

​Referencing a product in a debt

​Inline creation (productName)

​List products

​Update

​Deactivate

​Endpoints

Try it in the API Reference

Natural key: `name`

Create a product

Validations

Clients with several companies

Referencing a product in a debt

Inline creation (`productName`)

List products

Update

Deactivate

Endpoints