Retrieve the setup link for a subscription

POST

/v1/subscriptions/{subscriptionId}/setup

curl --request POST \
  --url https://api.timbro.do/v1/subscriptions/example/setup \
  --header 'Authorization: Bearer <token>'

• Production

Authentication

• secretKey

Parameters

Path parameters

subscriptionId

required

string

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

Subscription identity

Responses

200

200

Default Response

Media typeapplication/json

Response fields and codes

object

id

required

Subscription identity

string

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

subscriptionReference

required

string

terms

required

object

version

required

string

text

required

string

locale

required

Any of:

string

string

Allowed value: es

string

string

Allowed value: en

translations

required

object

es

required

string

en

required

string

customer

required

object

customerReference

required

string

>= 1 characters <= 128 characters

name

required

string

>= 1 characters <= 150 characters

email

required

string format: email

<= 254 characters

status

required

string

Allowed values: pending active past_due deferred canceled expired

amount

required

An exact decimal monetary amount.

object

currency

required

Example

DOP

string

/^[A-Z]{3}$/

value

required

Exact nonnegative decimal amount, with at most two fractional digits.

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

interval

required

object

unit

required

string

Allowed value: month

nextPaymentAt

required

Any of:

string

string format: date-time

null

null

setup

required

Any of:

SubscriptionSetupLink

object

url

required

Any of:

string

string format: uri

null

null

expiresAt

required

string format: date-time

null

null

management

required

Any of:

SubscriptionLink

object

url

required

string format: uri

null

null

managementLinkEmail

required

Any of:

SubscriptionManagementLinkEmail

object

status

required

Any of:

string

string

Allowed value: pending

string

string

Allowed value: accepted

string

string

Allowed value: failed

string

string

Allowed value: unknown

requestedAt

required

string format: date-time

null

null

deferralReason

required

Any of:

SubscriptionDeferralReason

string

Allowed values: merchant_account_not_ready recurring_account_required mandate_credential_unavailable business_fiscal_binding_unavailable business_fiscal_setup_unavailable subscription_invoicing_blocked card_enrollment_incomplete other

null

null

createdAt

required

string format: date-time

canceledAt

required

Any of:

string

string format: date-time

null

null

payments

required

Array<object>

<= 5 items

object

id

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

string

null

null

customerCheckoutUrl

required

Any of:

string

string format: uri

null

null

periodStart

required

Any of:

string

string format: date-time

null

null

periodEnd

required

Any of:

string

string format: date-time

null

null

initiator

required

Any of:

string

string

Allowed value: customer

string

string

Allowed value: merchant

recoveryNotice

required

Any of:

SubscriptionRecoveryNotice

object

status

required

Any of:

string

string

Allowed value: pending

string

string

Allowed value: accepted

string

string

Allowed value: failed

string

string

Allowed value: unknown

deadline

required

Any of:

string

string format: date-time

null

null

problem

required

Any of:

SubscriptionRecoveryNoticeProblem

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

null

null

null

null

invoicing

Any of:

PaymentInvoicing

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

object

mode

required

Any of:

string

string

Allowed value: automatic

string

string

Allowed value: merchant

string

string

Allowed value: existing

type

required

string

Allowed values: E31 E32 E45

recipientEmail

required

Any of:

string

string format: email

<= 320 characters

null

null

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

AnonymousBuyer

object

kind

required

string

Allowed values: anonymous

DomesticBuyer

object

kind

required

string

Allowed values: domestic

legalName

required

string

>= 1 characters <= 150 characters /^(?=.*[^\p{White_Space}])[\s\S]+$/

taxId

required

string

/^[0-9]{9}([0-9]{2})?$/

deliveryPhone

string

/^[0-9]{3}-[0-9]{3}-[0-9]{4}$/

ForeignBuyer

object

foreignId

required

string

>= 1 characters <= 20 characters /^(?=.*[^\p{White_Space}])[\s\S]+$/

kind

required

string

Allowed values: foreign

legalName

required

string

>= 1 characters <= 150 characters /^(?=.*[^\p{White_Space}])[\s\S]+$/

deliveryPhone

string

/^[0-9]{3}-[0-9]{3}-[0-9]{4}$/

governmentEligibility

Any of:

object

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

object

object

entityKind

required

string

Allowed value: decentralized_or_autonomous

authorityReference

required

string

>= 1 characters <= 128 characters

object

object

entityKind

required

string

Allowed value: social_security

authorityReference

required

string

>= 1 characters <= 128 characters

object

object

entityKind

required

string

Allowed value: other_noncommercial_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

null

null

paymentsHasMore

required

boolean

paymentsNextCursor

required

Any of:

string

string

null

null

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

400

400

The request could not be understood.

Media typeapplication/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

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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

401

401

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

403

403

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

404

404

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

Media typeapplication/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

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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

409

409

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.",
  "status": 409,
  "code": "subscription_setup_unavailable",
  "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_setup_unavailable

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 409

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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

500

500

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.