Subscriptions

List payments for a subscription

GET

/v1/subscriptions/{subscriptionId}/payments

const url = 'https://api.timbro.do/v1/subscriptions/example/payments?limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.timbro.do/v1/subscriptions/example/payments?limit=20' \
  --header 'Authorization: Bearer <token>'

Authentication

secretKey

Parameters

Path parameters

subscriptionId

required

string

/^sub_[0-9a-hjkmnp-tv-z]{24,}$/

Subscription identity

Query parameters

limit

integer

default: 20 >= 1 <= 100

Rows on one page.

cursor

string

>= 1 characters <= 512 characters

The nextCursor of the previous page. A cursor belongs to the list, tenant, mode, and filter set that minted it.

Responses

200

A page of payment history for one subscription.

application/json

Response fields and codes

A page of payment history for one subscription.

object

object

required

string

Allowed value: list

data

required

Array<object>

object

required

Payment identity

string

/^pay_[0-9a-hjkmnp-tv-z]{24,}$/

status

required

Only succeeded, canceled, and expired are terminal. A declined attempt returns the Payment to requires_customer_action with lastDecline, so the payer can try again until the Payment expires. partially_authorized means some shares have reserved funds, authorized means every share is reserved and awaits the organizer’s capture command, capturing means capture is running, and releasing means reserved funds are being released. verifying is a real, non-terminal status; it is not an error or decline.

string

Allowed values: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded canceled expired

invoiceId

required

Any of:

string
null

string

customerCheckoutUrl

required

Any of:

string
null

string format: uri

periodStart

required

Any of:

string
null

string format: date-time

periodEnd

required

Any of:

string
null

string format: date-time

initiator

required

Any of:

string
string

string

Allowed value: customer

recoveryNotice

required

Any of:

SubscriptionRecoveryNotice
null

object

status

required

Any of:

string

Allowed value: pending

deadline

required

Any of:

string
null

string format: date-time

problem

required

Any of:

SubscriptionRecoveryNoticeProblem
null

Why a recovery notice needs attention. notice_handoff_failed is a final provider rejection; notice_handoff_unknown is a handoff whose outcome is uncertain, retried until the provider’s deduplication window ends; notice_delivery_failed is a bounce or complaint after handoff; notice_unavailable means the notice could not be prepared yet.

string

Allowed values: notice_unavailable notice_handoff_failed notice_handoff_unknown notice_delivery_failed

invoicing

Any of:

PaymentInvoicing
null

Retained Invoice instructions and recipient choice. Invoice lifecycle and access credentials are reported separately.

object

mode

required

Any of:

string

Allowed value: automatic

type

required

string

Allowed values: E31 E32 E45

recipientEmail

required

Any of:

string
null

string format: email

<= 320 characters

issuanceProblem

One RFC 9457 problem body returned on the /v1 surface.

object

code

required

string

>= 1 characters

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

title

required

string

type

required

string

Allowed values: about:blank

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

buyer

discriminator: kind

object

kind

required

string

Allowed values: anonymous

governmentEligibility

Any of:

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

allowedTypes

Array<string>

Allowed values: E31 E32 E45

isTypeLocked

boolean

isBuyerLocked

boolean

revision

Increases each time the Invoice type, buyer, or government eligibility changes.

integer

>= 1

invoiceReference

string

>= 1 characters <= 128 characters

hasMore

required

True when a further page follows this one.

boolean

nextCursor

required

Any of:

string
null

string

>= 1 characters

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

400

The request could not be understood.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not be understood.",
  "status": 400,
  "code": "parameter_invalid",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: parameter_invalid collection_cursor_invalid

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 400

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

401

The credential is missing, malformed, or no longer valid.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is missing, malformed, or no longer valid.",
  "status": 401,
  "code": "api_key_missing",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 401

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

403

The credential is valid but not permitted to perform this operation.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is valid but not permitted to perform this operation.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: operation_not_permitted

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 403

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

404

No endpoint serves this method and path, or no resource with this identifier exists within the caller’s scope.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "No endpoint serves this method and path, or no resource with this identifier exists within the caller's scope.",
  "status": 404,
  "code": "subscription_not_found",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: subscription_not_found payment_not_found

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 404

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

500

The request could not complete. Recover by the retained resource reference or retry with the same command identity.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not complete. Recover by the retained resource reference or retry with the same command identity.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: internal_error

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 500

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.