> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# List Subscription Payments
> Returns the charge history for a subscription, including plan/phase context when applicable.
**This is a net-new endpoint**
There was no payments subresource before Plans — the `payments` array on [the subscription object](/reference/subscriptions/the-subscription-object) is a legacy, always-empty field. Since there's no prior merchant integration to preserve here, this endpoint ships as one clean `items[]` shape with full plan/phase context — no legacy fields.
**`offset` must be a multiple of `limit`**
A non-aligned `offset` would re-serve rows you already saw and corrupt `has_more`, so it's rejected with `400 BAD_REQUEST` instead of being silently floored.
**Free cycles are `total: 0`, not a distinct status**
A \$0 billing cycle (e.g. a free trial payment) is recognizable by `total == 0` — there's no separate "free" status.
## OpenAPI
````yaml openapi/subscriptions/list-subscription-payments.json GET /subscriptions/{subscription_id}/payments
openapi: 3.1.0
info:
title: subscription
version: 1.0.2
servers:
- url: https://api-sandbox.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/subscriptions/{subscription_id}/payments:
get:
summary: List Subscription Payments
description: >-
Returns the charge history for a subscription — one row per billing
attempt, including plan/phase context when the subscription is linked to
a plan. This is a net-new endpoint (there was no payments subresource
before Plans), so it ships as a single, clean shape with no legacy
fields to carry.
operationId: list-subscription-payments
parameters:
- name: subscription_id
in: path
description: The unique identifier of the subscription.
schema:
type: string
required: true
- name: limit
in: query
description: Max items to return. 1-100, defaults to 20.
schema:
type: integer
default: 20
minimum: 1
maximum: 100
- name: offset
in: query
description: >-
Number of items to skip. Must be a non-negative multiple of `limit`,
else `400 BAD_REQUEST` — a non-aligned offset would re-serve rows
you already saw and corrupt `has_more`. Defaults to 0.
schema:
type: integer
default: 0
minimum: 0
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
items:
- id: 00000000-0000-4000-8000-000000000010
payment_id: 00000000-0000-4000-8000-000000000011
idempotency_key: null
status: SUCCEEDED
sub_status: null
provider: PROVIDER_TEST
payment_method:
id: 00000000-0000-4000-8000-000000000012
type: CARD
amount:
currency: USD
value: 9.99
currency: USD
subtotal: 9.99
total: 9.99
plan_id: 00000000-0000-4000-8000-000000000001
line_items:
- type: PLAN
label: Intro
service_period:
start: '2024-04-01T09:00:00Z'
end: '2024-05-01T09:00:00Z'
amount:
currency: USD
value: 9.99
phase:
index: 1
name: Intro
type: TRIAL
phase_payment: 1
billing_cycle: null
retry:
count: 0
forced: false
trace_id: null
created_at: '2024-04-01T09:00:00.000000Z'
updated_at: '2024-04-01T09:00:00.000000Z'
pagination:
total: 1
limit: 20
offset: 0
has_more: false
schema:
type: object
properties:
items:
type: array
description: >-
Every payment attempt for this subscription, most recent
first.
items:
type: object
properties:
id:
type: string
payment_id:
type: string
idempotency_key:
type: string
status:
type: string
description: >-
Platform vocabulary: SUCCEEDED, DECLINED, REJECTED,
ERROR, PENDING, CREATED, CANCELED — not the engine's
internal EXECUTED.
sub_status:
type: string
provider:
type: string
description: >-
null for $0 cycles, the starter row, and rows
charged before the provider-capture field existed.
payment_method:
type: object
properties:
id:
type: string
type:
type: string
amount:
type: object
properties:
currency:
type: string
value:
type: number
currency:
type: string
subtotal:
type: number
total:
type: number
plan_id:
type: string
description: null for raw (non-plan) subscriptions.
line_items:
type: array
items:
type: object
properties:
type:
type: string
label:
type: string
service_period:
type: object
properties:
start:
type: string
end:
type: string
amount:
type: object
properties:
currency:
type: string
value:
type: number
phase:
type: object
description: >-
null for the starter row and for legacy (non-plan)
rows.
properties:
index:
type: integer
name:
type: string
type:
type: string
phase_payment:
type: integer
description: >-
1..N within the current phase. null on the starter
row.
billing_cycle:
type: integer
description: >-
0 = starter row, null = TRIAL-phase rows, 1.. from
the first REGULAR-phase payment.
retry:
type: object
properties:
count:
type: integer
forced:
type: boolean
trace_id:
type: string
created_at:
type: string
updated_at:
type: string
pagination:
type: object
properties:
total:
type: integer
limit:
type: integer
offset:
type: integer
has_more:
type: boolean
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````