Subscription Transactions

Query transactions charged under a subscription.

This service allows merchants to retrieve the full details of a subscription alongside the list of transactions that have been charged against it, filtered by a date range and an optional result size limit.

Keep in mind!

This endpoint requires your Private Key (Private-Merchant-Id) for authentication. Keep this credential secure and never expose it on client-side code.

How It Works

Send a GET request to /data/v1/subscription/{subscriptionId} using the target subscription ID as a path parameter. The response contains two main sections:

Subscription Details

Static metadata about the subscription — card info, plan name, periodicity, contact details, amount breakdown, and timestamps.

Transactions Array

The list of charges executed under that subscription within the requested date range, including status, amounts, and processor details.

The subscriptionId path parameter is the value returned as subscriptionId when a subscription is created via POST /subscriptions/v1/card.

Query Parameters

All query parameters are optional. If omitted, the following defaults apply:

Parameter	Type	Default	Description
`size`	integer	`100`	Maximum number of transactions to return. Must be a positive integer.
`start`	date (`YYYY-MM-DD`)	5 days before request	Start of the date range. Only transactions created on or after this date are returned.
`end`	date (`YYYY-MM-DD`)	Moment of request	End of the date range. Only transactions created on or before this date are returned.

Example request:

Response Structure

Subscription Details

The root-level fields describe the subscription itself — this data is static and reflects the subscription configuration at the time of the query.

Identification & Status

Periodicity & Schedule

Card & Contact

Amount

Field	Type	Description
`subscription_code`	string	Unique identifier of the subscription. Same value as `subscriptionId`.
`active_indicator`	boolean	Whether the subscription is currently active.
`plan_name`	string	Name of the plan associated with the subscription.
`provider_name`	string	Payment provider processing the subscription (e.g., `kushki`).
`reference_transaction_code`	string	Reference code of the initial validation transaction used to register the card.

Transactions Array

Each object inside the transactions[] array represents a single charge executed under the subscription.

Identification & Status

Amounts & Taxes

Card & Processor

Contact & Metadata

Field	Type	Description
`_id`	string	Internal unique identifier of the transaction record.
`ticket_code`	string	Ticket number assigned by Kushki.
`transaction_code`	string	Unique transaction identifier assigned by Kushki.
`approval_code`	string	Authorization code returned by the issuer upon approval.
`recap_code`	string	Reconciliation code for the transaction.
`reference_transaction_code`	string	UUID-based reference code for this transaction.
`subscription_code`	string	Identifier of the subscription this transaction belongs to.
`transaction_status_type`	string	Final status of the transaction. See values below.
`transaction_type`	string	Type of transaction executed. See values below.
`subscription_trigger_type`	string	How the charge was triggered: `onDemand` or `scheduled`.
`create_timestamp`	number	Unix timestamp (milliseconds) of when the transaction was created.

Transaction status values:

`transaction_status_type`	Meaning
`APPROVED`	Charge was authorized and captured successfully
`DECLINED`	Charge was rejected by the issuer
`INITIALIZED`	Charge was created but not yet resolved
`VOIDED`	Charge was reversed before settlement
`REFUNDED`	Charge was returned to the cardholder after settlement

Transaction type values:

`transaction_type`	Meaning
`SALE`	Standard charge
`PREAUTHORIZATION`	Authorization hold without capture
`CAPTURE`	Confirmation of a previous preauthorization
`VOID`	Reversal of a charge
`REFUND`	Post-settlement return

Error Codes

HTTP	Code	Message	Cause
`400`	`K001`	El cuerpo de la petición es inválido	Invalid or malformed request parameters
`401`	`K004`	Id de comercio no válido	Missing or invalid `Private-Merchant-Id`
`404`	`K037`	Subscripción no encontrada	The provided `subscriptionId` does not exist
`500`	`K002`	Ha ocurrido un error inesperado	Unexpected server-side error

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Get Subscription Transactions

Returns the subscription details and the list of charges executed within a date range. Requires Private Merchant ID.

Got a suggestion on this documentation? Contact us.

How It Works#

Query Parameters#

Response Structure#

Subscription Details#

Transactions Array#

Error Codes#

Using the API#

Available Endpoints#

How It Works

Query Parameters

Response Structure

Subscription Details

Transactions Array

Error Codes

Using the API

Available Endpoints