Planes

Los planes con precio fijo que ofreces (se crean en el panel).

Listar los planes

GET/v1/plans

Planes del entorno de la API key (pgm_test_ → sandbox, pgm_live_ → producción), más recientes primero. Sin status lista ACTIVE y ARCHIVED; para mostrar precios a tus usuarios, filtra status=ACTIVE.

Autenticación: Authorization: Bearer <API key>.

Parámetros

Parámetros de Listar los planes
Parámetro	En	Tipo	Descripción
`status`	query	string	Filtra por estado (sin distinguir mayúsculas); sin filtro, todos. Otro valor → `422 invalid_status`. Valores: `ACTIVE,` `ARCHIVED`
`limit`	query	integer	Tamaño de página (1–100, por defecto 50). Por defecto: `50`
`starting_after`	query	string	Id (`pln_…`) del último plan de la página anterior; otro formato → `422 invalid_cursor`; excluyente con `ending_before` (`422 invalid_cursor`).
`ending_before`	query	string	Id (`pln_…`) del primer plan de la página actual, para pedir la anterior (más recientes); excluyente con `starting_after` (`422 invalid_cursor`). Mismo orden (más recientes primero); `has_more` indica si hay más antes de esta página.

Respuestas

200Página de planes.

Esquema PlanList

Campos de la respuesta 200
Campo	Tipo	Descripción
`data`obligatorio	array<Plan>
`data[].id`obligatorio	string	Ejemplo: `pln_01JB86R800ABCDEFGHJKMNPQRS`
`data[].environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`data[].name`obligatorio	string	Ejemplo: `Pro`
`data[].description`obligatorio	string
`data[].amount_in_cents`obligatorio	integer (int64)	Precio en centavos (entero; $49.900 COP = `4990000`). Inmutable. Ejemplo: `4990000`
`data[].currency`obligatorio	string	Valores: `COP`
`data[].interval_unit`obligatorio	string	MVP: solo `MONTH`. Valores: `DAY,` `WEEK,` `MONTH,` `YEAR`
`data[].interval_count`obligatorio	integer	MVP: solo `1`.
`data[].trial_days`obligatorio	integer
`data[].status`obligatorio	string	Valores: `ACTIVE,` `ARCHIVED`
`data[].created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`data[].updated_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`data[].archived_at`obligatorio	string (date-time) \| null
`has_more`obligatorio	boolean

Errores

400: JSON mal formado o tipos inválidos (p. ej. decimales donde va un entero) (code invalid_body).
401: Credencial ausente, inválida, expirada o revocada (code unauthorized).
422: La entrada no cumple las reglas (type invalid_request; param indica el campo).
429: Demasiadas peticiones (type rate_limited, code rate_limited): más de 100 peticiones por segundo con la misma API key. Reintenta cuando indique Retry-After.
Otros: Error con el formato estándar.

Todos con el formato de error estándar.

Petición (cURL)

curl https://api.paygumi.com/v1/plans \
  -H "Authorization: Bearer pgm_test_..."

Respuesta 200

{
  "data": [
    {
      "id": "pln_01JB86R800ABCDEFGHJKMNPQRS",
      "environment": "SANDBOX",
      "name": "Pro",
      "description": "string",
      "amount_in_cents": 4990000,
      "currency": "COP",
      "interval_unit": "DAY",
      "interval_count": 1,
      "trial_days": 0,
      "status": "ACTIVE",
      "created_at": "2026-11-01T05:00:00Z",
      "updated_at": "2026-11-01T05:00:00Z",
      "archived_at": "2026-11-01T05:00:00Z"
    }
  ],
  "has_more": false
}