How to Automate Stripe Subscription Management using the API

Understanding the Stripe API

Setting Up Stripe API Authentication

Stripe Billing uses two keys for different purposes: the secret key (sk_*) for all server-side subscription management, and the publishable key (pk_*) for client-side Checkout Sessions and Elements. The Stripe SDK accepts the secret key directly at initialization. Test mode subscriptions use sk_test_* and generate no real charges.

1. 1Log in to your Stripe Dashboard at dashboard.stripe.com
2. 2Click 'Developers' then 'API keys' in the top navigation
3. 3Copy your secret key (sk_live_* for production) and publishable key (pk_live_* for frontend)
4. 4Set environment variables: STRIPE_SECRET_KEY=sk_live_... and STRIPE_PUBLISHABLE_KEY=pk_live_...
5. 5Set up a webhook endpoint at Developers > Webhooks > Add endpoint, subscribing to: invoice.paid, invoice.payment_failed, customer.subscription.deleted, customer.subscription.updated
6. 6Copy the webhook signing secret (whsec_*) and set STRIPE_WEBHOOK_SECRET environment variable
7. 7In your Stripe Dashboard, create Products and Prices (the price ID like price_* is what you pass to the subscriptions API)

1import os
2import stripe
3
4stripe.api_key = os.environ.get('STRIPE_SECRET_KEY')
5
6# Verify connectivity and list available prices
7prices = stripe.Price.list(active=True, limit=5)
8for price in prices.data:
9    print(f'{price.id}: {price.currency.upper()} {price.unit_amount/100:.2f}/{price.recurring.interval}')

Key endpoints

1{"customer": "cus_PqKLt2eZvKYlo2C", "items": [{"price": "price_1OqKLt2eZvKYlo2Cghi"}], "payment_settings": {"save_default_payment_method": "on_subscription"}, "expand": ["latest_invoice.payment_intent"]}

1{"id": "sub_1OqKMj2eZvKYlo2C", "object": "subscription", "customer": "cus_PqKLt2eZvKYlo2C", "status": "active", "current_period_start": 1706745820, "current_period_end": 1709424220, "items": {"data": [{"id": "si_1OqKMj", "price": {"id": "price_1OqKLt", "unit_amount": 2900, "currency": "usd", "recurring": {"interval": "month"}}}]}, "latest_invoice": {"payment_intent": {"status": "succeeded"}}}

1{"items": [{"id": "si_1OqKMj", "price": "price_1NewPlanId"}], "proration_behavior": "always_invoice"}

1{"id": "sub_1OqKMj2eZvKYlo2C", "status": "active", "items": {"data": [{"id": "si_1OqKMj", "price": {"id": "price_1NewPlanId", "unit_amount": 9900}}]}}

1{"cancellation_details": {"comment": "Canceled via self-service portal", "feedback": "too_expensive"}}

1{"id": "sub_1OqKMj2eZvKYlo2C", "status": "canceled", "canceled_at": 1706745900, "current_period_end": 1709424220}

1{"object": "list", "data": [{"id": "sub_1OqKMj", "status": "active", "customer": "cus_PqKLt2", "current_period_end": 1709424220}], "has_more": false}

Step-by-step automation

1# 1. Create customer
2curl https://api.stripe.com/v1/customers \
3  -u "$STRIPE_SECRET_KEY:" \
4  -d email="user@example.com" \
5  -d "metadata[user_id]"="usr_123abc"
6
7# 2. Attach payment method (pm_* from Stripe.js/Elements on frontend)
8curl https://api.stripe.com/v1/payment_methods/pm_1OqKLt2eZvKYlo2Cabc/attach \
9  -u "$STRIPE_SECRET_KEY:" \
10  -d customer="cus_PqKLt2eZvKYlo2C"
11
12# 3. Set as default
13curl https://api.stripe.com/v1/customers/cus_PqKLt2eZvKYlo2C \
14  -u "$STRIPE_SECRET_KEY:" \
15  -d "invoice_settings[default_payment_method]"="pm_1OqKLt2eZvKYlo2Cabc"

1curl https://api.stripe.com/v1/subscriptions \
2  -u "$STRIPE_SECRET_KEY:" \
3  -d customer="cus_PqKLt2eZvKYlo2C" \
4  -d "items[0][price]"="price_1OqKLt2eZvKYlo2Cghi" \
5  -d "payment_settings[save_default_payment_method]"="on_subscription" \
6  -d "expand[]"="latest_invoice.payment_intent"

1# Get the subscription item ID first
2SUB_ITEM_ID=$(curl -s https://api.stripe.com/v1/subscriptions/sub_1OqKMj2eZvKYlo2C \
3  -u "$STRIPE_SECRET_KEY:" | python3 -c "import sys,json; print(json.load(sys.stdin)['items']['data'][0]['id'])")
4
5# Upgrade to new price, charge proration immediately
6curl -X POST https://api.stripe.com/v1/subscriptions/sub_1OqKMj2eZvKYlo2C \
7  -u "$STRIPE_SECRET_KEY:" \
8  -d "items[0][id]"="$SUB_ITEM_ID" \
9  -d "items[0][price]"="price_1NewPlanId" \
10  -d proration_behavior="always_invoice"

1# Register webhook for payment failure events
2curl https://api.stripe.com/v1/webhook_endpoints \
3  -u "$STRIPE_SECRET_KEY:" \
4  -d url="https://yourapp.com/webhooks/stripe" \
5  -d "enabled_events[]"="invoice.payment_failed" \
6  -d "enabled_events[]"="invoice.paid" \
7  -d "enabled_events[]"="customer.subscription.deleted"

Complete working code

A complete subscription management module handling creation, plan changes, cancellation, and webhook processing. This shows the full integration pattern for a SaaS application — create customers, manage subscriptions, and react to billing events.

1import stripe
2import os
3import logging
4from flask import Flask, request, jsonify
5
6logging.basicConfig(level=logging.INFO)
7log = logging.getLogger(__name__)
8
9stripe.api_key = os.environ['STRIPE_SECRET_KEY']
10WEBHOOK_SECRET = os.environ['STRIPE_WEBHOOK_SECRET']
11
12app = Flask(__name__)
13
14# --- Subscription Management Functions ---
15
16def get_or_create_customer(email, user_id):
17    existing = stripe.Customer.search(query=f'metadata["user_id"]:"{user_id}"')
18    if existing.data:
19        return existing.data[0].id
20    customer = stripe.Customer.create(email=email, metadata={'user_id': user_id})
21    log.info(f'Created customer {customer.id} for user {user_id}')
22    return customer.id
23
24def create_subscription(customer_id, price_id, trial_days=0):
25    params = {
26        'customer': customer_id,
27        'items': [{'price': price_id}],
28        'payment_settings': {'save_default_payment_method': 'on_subscription'},
29        'expand': ['latest_invoice.payment_intent']
30    }
31    if trial_days > 0:
32        import time
33        params['trial_end'] = int(time.time()) + trial_days * 86400
34
35    sub = stripe.Subscription.create(**params)
36    log.info(f'Subscription {sub.id} created, status: {sub.status}')
37    return sub
38
39def cancel_subscription(subscription_id, at_period_end=True):
40    if at_period_end:
41        sub = stripe.Subscription.modify(subscription_id, cancel_at_period_end=True)
42        log.info(f'Subscription {subscription_id} will cancel at period end')
43    else:
44        sub = stripe.Subscription.delete(subscription_id)
45        log.info(f'Subscription {subscription_id} canceled immediately')
46    return sub
47
48# --- Webhook Handler ---
49
50@app.route('/webhooks/stripe', methods=['POST'])
51def webhook():
52    payload = request.get_data()  # RAW body — must not be parsed first
53    sig = request.headers.get('Stripe-Signature')
54
55    try:
56        event = stripe.Webhook.construct_event(payload, sig, WEBHOOK_SECRET)
57    except stripe.error.SignatureVerificationError:
58        log.warning('Invalid webhook signature')
59        return jsonify({'error': 'Invalid signature'}), 400
60
61    obj = event.data.object
62    etype = event.type
63
64    if etype == 'invoice.paid':
65        log.info(f'Invoice paid: sub={obj.subscription}, customer={obj.customer}')
66        # grant_user_access(obj.customer)
67
68    elif etype == 'invoice.payment_failed':
69        log.warning(f'Payment failed attempt {obj.attempt_count}: sub={obj.subscription}')
70        # send_dunning_email(obj.customer_email, obj.attempt_count)
71        # if obj.attempt_count >= 3: restrict_access(obj.customer)
72
73    elif etype == 'customer.subscription.updated':
74        log.info(f'Subscription updated: {obj.id}, status={obj.status}')
75
76    elif etype == 'customer.subscription.deleted':
77        log.info(f'Subscription canceled: {obj.id}')
78        # revoke_user_access(obj.customer)
79
80    return jsonify({'status': 'ok'})
81
82if __name__ == '__main__':
83    app.run(port=3000)

Error handling

Rate Limits for Stripe API

1import time
2import stripe
3
4def stripe_with_retry(fn, max_retries=5):
5    for attempt in range(max_retries):
6        try:
7            return fn()
8        except stripe.error.RateLimitError:
9            wait = min(2 ** attempt, 32)
10            print(f'Rate limit hit, waiting {wait}s')
11            time.sleep(wait)
12        except stripe.error.APIConnectionError as e:
13            if attempt == max_retries - 1: raise
14            time.sleep(2 ** attempt)
15    raise Exception('Max retries exceeded')

• Process subscription changes asynchronously via a job queue (Celery, BullMQ) to avoid blocking requests and to handle billing cycle webhook spikes
• Return 200 from webhook endpoints immediately, then process the event asynchronously — Stripe marks your endpoint as failed if no 2xx within 30 seconds
• Use Stripe's idempotency keys when creating subscriptions: add Idempotency-Key: {unique-id} header to prevent duplicate subscriptions from retry logic
• Cache subscription status in your database and update via webhooks — avoid calling GET /v1/subscriptions on every page load
• Subscribe only to the webhook events you handle — unused events still count toward webhook delivery retries

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Grant application access based on invoice.paid webhook events, not the subscription creation API response — payment can fail asynchronously
• Use payment_behavior='default_incomplete' for subscription creation so the subscription stays inactive until first payment succeeds
• Preview proration amounts with POST /v1/subscriptions/{id}/upcoming_invoice before applying plan changes to show customers what they'll be charged
• Always specify cancel_at_period_end=true for customer-initiated cancellations — immediate cancellation with no refund is surprising and generates disputes
• Implement idempotency keys (Idempotency-Key header) for subscription creation to prevent duplicate charges from network timeouts
• Use Stripe's Smart Retries (Billing > Settings) which automatically retries failed payments at optimal times based on card network signals
• Store Stripe customer IDs and subscription IDs in your database immediately on creation — use Stripe's customer search as a fallback only

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations

Explore related guides

Guides from other topics that help with this issue