# Tutorial: Get Started with FastStripe


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Prerequisites

Before starting this tutorial, you’ll need:

- Python 3.9 or higher installed
- A Stripe account (sign up at [stripe.com](https://stripe.com))
- Your Stripe test API keys from the [Stripe
  Dashboard](https://dashboard.stripe.com/test/apikeys)

## Why FastStripe?

FastStripe offers several advantages over the official Stripe Python
SDK:

- **Self-documenting**: See all available parameters with descriptions
  in your IDE
- **Simplified workflows**: High-level methods for common payment
  patterns
- **Lightweight**: Minimal dependencies (just `fastcore`)
- **Consistent API**: HTTP verb-based methods (`post`, `get`) with full
  parameter visibility

## Step 1: Installation

First, install FastStripe using pip:

``` bash
pip install faststripe
```

Or install the latest development version:

``` bash
pip install git+https://github.com/AnswerDotAI/faststripe.git
```

## Versioning

FastStripe versions follow Stripe’s API versioning scheme (e.g.,
`2025.05.28.x`). Each FastStripe release is pinned to a specific Stripe
API version, ensuring:

- **Stability**: Your code won’t break when Stripe updates their API
- **Predictability**: Same behavior across all environments  
- **Compatibility**: Choose the Stripe API version that works for your
  application

When you install FastStripe, you get a specific snapshot of the Stripe
API that’s been tested and validated. The minor version represents
non-breaking changes we add such as better higher-level APIs.

## Step 2: Set up your API key

For this tutorial, you’ll use your Stripe test API key. Create a `.env`
file in your project directory:

``` bash
echo "STRIPE_SECRET_KEY=sk_test_your_test_key_here" > .env
```

Then load it in your Python environment:

## Step 3: Initialize FastStripe

Now let’s import FastStripe and initialize it with your API key:

``` python
from faststripe.core import *

# Initialize with your API key from environment
sapi = StripeApi('your-api-key')
```

``` python
sapi.customers.post
```

[customers.post](https://docs.stripe.com/api/customers/create)(address:
object = None, balance: int = None, business_name: object = None,
cash_balance: dict = None, description: str = None, email: str = None,
expand: list = None, individual_name: object = None, invoice_prefix: str
= None, invoice_settings: dict = None, metadata: object = None, name:
str = None, next_invoice_sequence: int = None, payment_method: str =
None, phone: str = None, preferred_locales: list = None, shipping:
object = None, source: str = None, tax: dict = None, tax_exempt: str =
None, tax_id_data: list = None, test_clock: str = None): *Create a
customer*

``` python
# Create a customer
customer = sapi.customers.post(email='user@example.com', name='John Doe')
print(customer.id, customer.email)
```

    cus_TuFzNNxCMjVmcw user@example.com

### Self-Documenting API

One of FastStripe’s key advantages is that all methods include parameter
documentation directly in your IDE. You can see what parameters are
available without checking external docs:

``` python
# Explore available methods and their parameters
sapi.customers.post?
```

    Signature:     
    sapi.customers.post(
        address: object = None,
        balance: int = None,
        cash_balance: dict = None,
        description: str = None,
        email: str = None,
        ...

It also supports tab completion when filling in parameters!

### High-Level Convenience Methods

FastStripe includes simplified methods for common payment workflows:

``` python
# Create a one-time payment checkout session
checkout = sapi.one_time_payment(
    product_name='My Product',
    amount_cents=20_00,  # $20.00
    success_url='https://localhost:8000/success',
    cancel_url='https://localhost:8000/cancel'
)
print(f"Payment URL: {checkout.url[:64]}...")
```

    Payment URL: https://billing.answer.ai/c/pay/cs_test_a1pzRLNdTHBkHW5IkgHHRKgX...

``` python
# Create a subscription checkout session
subscription = sapi.subscription(
    product_name='Monthly Plan',
    amount_cents=9_99,  # $9.99/month
    success_url='https://localhost:8000/success',
    cancel_url='https://localhost:8000/cancel',
    customer_email=customer.email
)
print(f"Subscription URL: {subscription.url[:64]}...")
```

    Subscription URL: https://billing.answer.ai/c/pay/cs_test_a1qd9Z83fYA9SdquEKozlgWB...

### Complete API Coverage

FastStripe provides access to the entire Stripe API through organized
resource groups:

``` python
# Access any Stripe resource with consistent patterns
product = sapi.products.post(name='New Product')
print(f"Created product: {product.name} with ID: {product.id}")
```

    Created product: New Product with ID: prod_TuG0pr2pvrb77d

``` python
# Fetch existing resources
customers = sapi.customers.get(limit=3)
print(f"Found {len(customers.data)} customers")
```

    Found 3 customers

``` python
# All responses are AttrDict objects for easy dot notation access
payment_intent = sapi.payment.intents_post(amount=1000, currency='usd')
print(f"Payment intent status: {payment_intent.status}, amount: ${payment_intent.amount/100}")
```

    Payment intent status: requires_payment_method, amount: $10.0

### Pagination Support

FastStripe includes built-in utilities for handling paginated API
responses, making it easy to work with large requests.

``` python
for p in paged(sapi.customers.get, limit=5): break
print(f"Got {len(p.data)} customers")
print(f"Has more pages: {p.has_more}")
```

    Got 5 customers
    Has more pages: True

``` python
sapi.products
```

- [products.get](https://docs.stripe.com/api/products/list)(active:
  ‘str’ = None, created: ‘str’ = None, ending_before: ‘str’ = None,
  expand: list = None, ids: ‘str’ = None, limit: ‘str’ = None,
  shippable: ‘str’ = None, starting_after: ‘str’ = None, url: ‘str’ =
  None): *List all products*
- [products.post](https://docs.stripe.com/api/products/create)(active:
  bool = None, default_price_data: dict = None, description: str = None,
  expand: list = None, id: str = None, images: list = None,
  marketing_features: list = None, metadata: dict = None, name: str =
  None, package_dimensions: dict = None, shippable: bool = None,
  statement_descriptor: str = None, tax_code: str = None, unit_label:
  str = None, url: str = None): *Create a product*
- [products.search_get](https://docs.stripe.com/api/searchs/retrieve)(expand:
  list = None, limit: ‘str’ = None, page: ‘str’ = None, query: ‘str’ =
  None): *Search products*
- [products.id_delete](https://docs.stripe.com/api/products/delete)(id):
  *Delete a product*
- [products.id_get](https://docs.stripe.com/api/products/delete)(id,
  expand: list = None): *Retrieve a product*
- [products.id_post](https://docs.stripe.com/api/products/update)(id,
  active: bool = None, default_price: str = None, description: object =
  None, expand: list = None, images: object = None, marketing_features:
  object = None, metadata: object = None, name: str = None,
  package_dimensions: object = None, shippable: bool = None,
  statement_descriptor: str = None, tax_code: object = None, unit_label:
  object = None, url: object = None): *Update a product*
- [products.product_features_get](https://docs.stripe.com/api/features/delete)(product,
  ending_before: ‘str’ = None, expand: list = None, limit: ‘str’ = None,
  starting_after: ‘str’ = None): *List all features attached to a
  product*
- [products.product_features_post](https://docs.stripe.com/api/features/update)(product,
  entitlement_feature: str = None, expand: list = None): *Attach a
  feature to a product*
- [products.product_features_id_delete](https://docs.stripe.com/api/features/delete)(product,
  id): *Remove a feature from a product*
- [products.product_features_id_get](https://docs.stripe.com/api/features/delete)(product,
  id, expand: list = None): *Retrieve a product_feature*

``` python
products = pages(sapi.products.get, limit=10)
len(products), products[0]
```

    (932,
     {'id': 'prod_TuG0pr2pvrb77d',
      'object': 'product',
      'active': True,
      'attributes': [],
      'created': 1770055482,
      'default_price': {},
      'description': {},
      'images': [],
      'livemode': False,
      'marketing_features': [],
      'metadata': {},
      'name': 'New Product',
      'package_dimensions': {},
      'shippable': {},
      'statement_descriptor': {},
      'tax_code': {},
      'type': 'service',
      'unit_label': {},
      'updated': 1770055482,
      'url': {}})

The pagination utilities work with any Stripe resource that supports
pagination:

- **[`paged()`](https://AnswerDotAI.github.io/faststripe/core.html#paged)**:
  Creates a paged generator for a resource’s API
- **[`pages()`](https://AnswerDotAI.github.io/faststripe/core.html#pages)**:
  Iterator that automatically fetches all pages and returns all items
  returned in those pages

This makes it easy to process large datasets without manually handling
pagination tokens.