How to Automate Stripe Customer Management using the API

Understanding the Stripe API

Setting Up Stripe API Authentication

Stripe uses simple API key authentication. For customer management, you only need the secret key. The test and live environments are completely isolated — make sure to use the right key for each environment to avoid the 'No such customer' error from mode mismatches.

1. 1Log in to your Stripe Dashboard at dashboard.stripe.com
2. 2Click 'Developers' in the top navigation, then 'API keys'
3. 3Copy your Secret key — sk_live_* for production, sk_test_* for development
4. 4Set STRIPE_SECRET_KEY environment variable in your application
5. 5Confirm the key works with a test call to GET /v1/customers?limit=1
6. 6For restricted access, create a Restricted key at Developers > API keys with 'Write' access to Customers only

1import os
2import stripe
3
4stripe.api_key = os.environ.get('STRIPE_SECRET_KEY')
5
6# Confirm environment (live vs test)
7try:
8    customers = stripe.Customer.list(limit=1)
9    mode = 'live' if not customers.data[0].livemode else 'test' if customers.data else 'unknown'
10    print(f'Connected to Stripe {mode} mode')
11except stripe.error.InvalidRequestError:
12    # No customers yet is fine
13    print('Stripe connected — no customers yet')

Key endpoints

1{"email": "alice@example.com", "name": "Alice Johnson", "metadata": {"user_id": "usr_abc123", "plan": "free", "signup_source": "organic"}}

1{"id": "cus_PqKLt2eZvKYlo2C", "object": "customer", "email": "alice@example.com", "name": "Alice Johnson", "created": 1706745700, "livemode": true, "metadata": {"user_id": "usr_abc123", "plan": "free"}, "subscriptions": {"data": []}, "default_source": null}

1{"metadata": {"plan": "pro", "company": "Acme Corp", "ltv": "2400"}}

1{"id": "cus_PqKLt2eZvKYlo2C", "metadata": {"user_id": "usr_abc123", "plan": "pro", "company": "Acme Corp", "ltv": "2400"}}

1{"object": "search_result", "data": [{"id": "cus_PqKLt2eZvKYlo2C", "email": "alice@example.com", "metadata": {"user_id": "usr_abc123"}}], "has_more": false}

1{"customer": "cus_PqKLt2eZvKYlo2C"}

1{"id": "pm_1OqKLt2eZvKYlo2Cabc", "object": "payment_method", "type": "card", "card": {"brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2027}, "customer": "cus_PqKLt2eZvKYlo2C"}

Step-by-step automation

1curl https://api.stripe.com/v1/customers \
2  -u "$STRIPE_SECRET_KEY:" \
3  -d email="alice@example.com" \
4  -d name="Alice Johnson" \
5  -d "metadata[user_id]"="usr_abc123" \
6  -d "metadata[plan]"="free" \
7  -d "metadata[signup_source]"="organic"

1# Update customer plan tier and company in metadata
2curl https://api.stripe.com/v1/customers/cus_PqKLt2eZvKYlo2C \
3  -u "$STRIPE_SECRET_KEY:" \
4  -d "metadata[plan]"="pro" \
5  -d "metadata[company]"="Acme Corp" \
6  -d "metadata[ltv]"="2400"
7
8# Delete a metadata key by setting it to empty string
9curl https://api.stripe.com/v1/customers/cus_PqKLt2eZvKYlo2C \
10  -u "$STRIPE_SECRET_KEY:" \
11  -d "metadata[old_field]"=""

1# Attach payment method to customer
2curl https://api.stripe.com/v1/payment_methods/pm_1OqKLt2eZvKYlo2Cabc/attach \
3  -u "$STRIPE_SECRET_KEY:" \
4  -d customer="cus_PqKLt2eZvKYlo2C"
5
6# Set as default for invoices
7curl https://api.stripe.com/v1/customers/cus_PqKLt2eZvKYlo2C \
8  -u "$STRIPE_SECRET_KEY:" \
9  -d "invoice_settings[default_payment_method]"="pm_1OqKLt2eZvKYlo2Cabc"

1# Search by email
2curl "https://api.stripe.com/v1/customers/search?query=email%3A%22alice%40example.com%22" \
3  -u "$STRIPE_SECRET_KEY:"
4
5# Search by metadata field
6curl "https://api.stripe.com/v1/customers/search?query=metadata%5B%22plan%22%5D%3A%22pro%22&limit=100" \
7  -u "$STRIPE_SECRET_KEY:"

Complete working code

A complete customer lifecycle management module: create on signup with duplicate prevention, sync metadata on profile changes, attach payment methods, and look up customers. This is the foundation for any Stripe integration.

1import stripe
2import os
3import logging
4
5logging.basicConfig(level=logging.INFO)
6log = logging.getLogger(__name__)
7
8stripe.api_key = os.environ['STRIPE_SECRET_KEY']
9
10class StripeCustomerManager:
11
12    def get_or_create(self, user_id, email, name):
13        # Check by metadata first (most reliable)
14        existing = stripe.Customer.search(
15            query=f'metadata["user_id"]:"{user_id}"'
16        )
17        if existing.data:
18            log.info(f'Found existing customer {existing.data[0].id} for user {user_id}')
19            return existing.data[0]
20
21        customer = stripe.Customer.create(
22            email=email,
23            name=name,
24            metadata={'user_id': user_id, 'plan': 'free'}
25        )
26        log.info(f'Created customer {customer.id} for user {user_id}')
27        return customer
28
29    def update_metadata(self, customer_id, updates):
30        customer = stripe.Customer.modify(customer_id, metadata=updates)
31        log.info(f'Updated {customer_id}: {list(updates.keys())}')
32        return customer
33
34    def attach_card(self, customer_id, payment_method_id):
35        pm = stripe.PaymentMethod.attach(payment_method_id, customer=customer_id)
36        stripe.Customer.modify(
37            customer_id,
38            invoice_settings={'default_payment_method': payment_method_id}
39        )
40        log.info(f'Attached {pm.card.brand} **** {pm.card.last4} to {customer_id}')
41        return pm
42
43    def get_by_user_id(self, user_id):
44        results = stripe.Customer.search(
45            query=f'metadata["user_id"]:"{user_id}"'
46        )
47        return results.data[0] if results.data else None
48
49    def list_payment_methods(self, customer_id):
50        return stripe.PaymentMethod.list(customer=customer_id, type='card').data
51
52    def delete(self, customer_id):
53        deleted = stripe.Customer.delete(customer_id)
54        log.info(f'Deleted customer {customer_id}')
55        return deleted
56
57
58# Usage
59manager = StripeCustomerManager()
60
61# On user signup
62customer = manager.get_or_create('usr_abc123', 'alice@example.com', 'Alice Johnson')
63print(f'Customer ID: {customer.id}')
64
65# After plan upgrade
66manager.update_metadata(customer.id, {'plan': 'pro', 'upgraded_at': '2024-02-01'})
67
68# After adding payment method via Stripe Elements
69# manager.attach_card(customer.id, 'pm_from_frontend')

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 limited, retrying in {wait}s')
11            time.sleep(wait)
12        except stripe.error.APIConnectionError:
13            if attempt == max_retries - 1: raise
14            time.sleep(2 ** attempt)
15    raise Exception('Max retries')

• Cache the user_id → Stripe customer_id mapping in your own database — a single DB query is faster than a Stripe API call
• Use GET /v1/customers with cursor-based pagination for bulk customer operations instead of search
• Avoid calling GET /v1/customers/search in real-time request paths — use it for batch jobs only
• Batch metadata updates: if multiple fields change in one user action, send them in a single PATCH call
• Use Stripe's SDK auto-pagination (auto_paging_iter) for list endpoints to handle cursor management automatically

Security checklist

Automation use cases

No-code alternatives

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

Best practices

• Create exactly one Stripe customer per user and store the customer ID in your database — never create duplicate customers for the same user
• Store your internal user ID in customer metadata immediately on creation to enable two-way lookup without relying on email (which can change)
• Always verify the test/live mode environment matches before customer operations — 'No such customer' is almost always a mode mismatch
• Use the search API as a fallback, not a primary lookup path — your own database is faster and not rate-limited
• Set the default payment method explicitly after attaching it — Stripe does not automatically set the first attached card as default
• For GDPR/CCPA compliance, call DELETE /v1/customers/{id} to purge PII — this deletes email, name, and contact info from Stripe's servers
• Keep metadata values as strings and limit to short IDs and flags — store complex data in your database and link via ID

Ask AI to help

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

Related automations