The Subscription object
Subscriptions allow you to charge a customer on a recurring basis in USDC.
Attributes
id string Unique identifier for the object. Zoneless subscription IDs are prefixed with sub_z_.
customer string ID of the customer who owns the subscription.
status enum For collection_method=charge_automatically, a subscription moves into incomplete if the initial USDC wallet payment fails. Once the first invoice is paid, the subscription becomes active. If the first invoice isn't paid within 23 hours, the subscription transitions to incomplete_expired. A subscription in a trial period is trialing and moves to active when the trial ends. A subscription can only enter paused when a trial ends without a payment method. If collection is automatic, the subscription becomes past_due when payment is required but the customer's wallet payment can't be completed; after retries are exhausted it becomes canceled or unpaid depending on your settings.
incompleteInitial payment hasn't succeeded yet.incomplete_expiredInitial invoice wasn't paid within 23 hours. Terminal status.trialingCurrently in a trial period.activeIn good standing and generating invoices.past_duePayment is required but hasn't succeeded yet.canceledCanceled and no longer generating invoices.unpaidPayment retries exhausted; invoices may remain open.pausedTrial ended without a payment method; no invoices are generated until resumed.items object List of subscription items, each with an attached price.
latest_invoicenullable string The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).
currency enum Three-letter ISO currency code, in lowercase. Always usdc for Zoneless.
Difference from Stripe: Uses usdc instead of fiat currency codes like usd.
usdccollection_method enum Either charge_automatically or send_invoice. When charging automatically, Zoneless attempts to pay this subscription at the end of the cycle using the customer's default payment method (typically a crypto wallet). When sending an invoice, Zoneless emails your customer an invoice with payment instructions and marks the subscription as active.
charge_automaticallysend_invoicecancel_at_period_end boolean Whether this subscription will (if status=active) or did (if status=canceled) cancel at the end of the current billing period.
billing_cycle_anchor timestamp The reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. The timestamp is in UTC format.
default_payment_methodnullable string ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source.
trial_endnullable timestamp If the subscription has a trial, the end of that trial.
trial_startnullable timestamp If the subscription has a trial, the beginning of that trial.
metadata object Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
descriptionnullable string The subscription's description, meant to be displayable to the customer. Maximum length is 500 characters.
More attributes
{
"id": "sub_z_1QvK9mR2eZvKYlo2CxH4pN8w",
"object": "subscription",
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"disabled_reason": null,
"liability": null
},
"billing_cycle_anchor": 1784745600,
"billing_cycle_anchor_config": null,
"billing_mode": {
"type": "flexible",
"flexible": {
"proration_discounts": "included"
},
"updated_at": 1784745600
},
"billing_schedules": [],
"billing_thresholds": null,
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created": 1784745600,
"currency": "usdc",
"customer": "cus_z_MayaChen91kL2",
"customer_account": null,
"days_until_due": null,
"default_payment_method": "pm_z_cryptoWallet7Hx",
"default_source": null,
"default_tax_rates": [],
"description": "Pro membership",
"discounts": [],
"ended_at": null,
"invoice_settings": {
"account_tax_ids": null,
"custom_fields": null,
"description": null,
"footer": null,
"issuer": {
"type": "self",
"account": null
}
},
"items": {
"object": "list",
"data": [
{
"id": "si_z_9Km2pQxR4vL8nHw",
"object": "subscription_item",
"billed_until": null,
"billing_thresholds": null,
"created": 1784745601,
"current_period_end": 1787424000,
"current_period_start": 1784745600,
"discounts": [],
"metadata": {},
"price": "price_z_ProMonthly25",
"quantity": 1,
"subscription": "sub_z_1QvK9mR2eZvKYlo2CxH4pN8w",
"tax_rates": [],
"platform_account": "acct_z_Platform123abc"
}
],
"has_more": false,
"url": "/v1/subscription_items?subscription=sub_z_1QvK9mR2eZvKYlo2CxH4pN8w"
},
"latest_invoice": "in_z_1QvK9nT3eZvKYlo2C8mR2qPx",
"livemode": false,
"managed_payments": null,
"metadata": {},
"next_pending_invoice_item_invoice": null,
"on_behalf_of": null,
"pause_collection": null,
"payment_settings": {
"payment_method_options": {
"crypto": {
"setup_future_usage": "none"
}
},
"payment_method_types": ["crypto"],
"save_default_payment_method": "off"
},
"pending_invoice_item_interval": null,
"pending_setup_intent": null,
"pending_update": null,
"presentment_details": null,
"schedule": null,
"start_date": 1784745600,
"status": "active",
"test_clock": null,
"transfer_data": null,
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"platform_account": "acct_z_Platform123abc",
"subscription_delegation_pda": "7xK9Nv3F...abc123",
"billing_lock_until": null
}