Metadata-Version: 2.4
Name: faststripe
Version: 2026.4.22.0
Summary: Fastest way to use the Stripe API in python
Author-email: ncoop57 <nathanacooper@proton.me>
License: Apache-2.0
Project-URL: Repository, https://github.com/AnswerDotAI/faststripe
Project-URL: Documentation, https://AnswerDotAI.github.io/faststripe
Keywords: nbdev,jupyter,notebook,python
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: fastspec>=0.0.5
Requires-Dist: httpx
Requires-Dist: nbdev>=3
Provides-Extra: dev
Requires-Dist: llms-txt; extra == "dev"
Requires-Dist: python-fasthtml; extra == "dev"
Dynamic: license-file

# Tutorial: Get Started with FastStripe


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

## Prerequisites

Before starting this tutorial, you’ll need:

- Python 3.10 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 available parameters with descriptions in
  your IDE
- **Generated from Stripe’s OpenAPI spec**: Endpoints are built from a
  pinned Stripe API snapshot
- **Lightweight**: Small runtime built on `fastcore`, `fastspec`, and
  `httpx`
- **Consistent API**: Nested Stripe resources use HTTP verb methods
  (`post`, `get`) with visible parameters

## 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: Get your API key

For this tutorial, use your Stripe test API key from the Stripe
Dashboard. We’ll pass it explicitly with `api_key=` so the setup is
visible in the code.

Use a test key while following the tutorial. Test secret keys start with
`sk_test_` and should still be treated as private.

## Step 3: Initialize FastStripe

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

``` python
from faststripe.core import *

# Initialize with your Stripe test API key
sapi = StripeApi(api_key='sk_test_your_test_key_here')
```

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

<div class="prose" markdown="1">

Create a customer

Parameters: - address (, optional): The customer’s address. Learn about
[country-specific requirements for calculating
tax](https://docs.stripe.com/invoicing/taxes?dashboard-or-api=dashboard#set-up-customer). -
balance (int, optional): An integer amount in cents (or local
equivalent) that represents the customer’s current balance, which affect
the customer’s future invoices. A negative amount represents a credit
that decreases the amount due on an invoice; a positive amount increases
the amount due on an invoice. - business_name (str, optional): The
customer’s business name. This may be up to *150 characters*. -
cash_balance (dict, optional): Balance information and default balance
settings for this customer. - description (str, optional): An arbitrary
string that you can attach to a customer object. It is displayed
alongside the customer in the dashboard. - email (str, optional):
Customer’s email address. It’s displayed alongside the customer in your
dashboard and can be useful for searching and tracking. This may be up
to *512 characters*. - expand (list, optional): Specifies which fields
in the response should be expanded. - individual_name (str, optional):
The customer’s full name. This may be up to *150 characters*. -
invoice_prefix (str, optional): The prefix for the customer used to
generate unique invoice numbers. Must be 3–12 uppercase letters or
numbers. - invoice_settings (dict, optional): Default invoice settings
for this customer. - metadata (, optional): Set of [key-value
pairs](https://docs.stripe.com/api/metadata) that you can attach to an
object. This can be useful for storing additional information about the
object in a structured format. Individual keys can be unset by posting
an empty value to them. All keys can be unset by posting an empty value
to `metadata`. - name (str, optional): The customer’s full name or
business name. - next_invoice_sequence (int, optional): The sequence to
be used on the customer’s next invoice. Defaults to 1. - payment_method
(str, optional) - phone (str, optional): The customer’s phone number. -
preferred_locales (list, optional): Customer’s preferred languages,
ordered by preference. - shipping (, optional): The customer’s shipping
information. Appears on invoices emailed to this customer. - source
(str, optional) - tax (dict, optional): Tax details about the
customer. - tax_exempt (str, optional): The customer’s tax exemption.
One of `none`, `exempt`, or `reverse`. - tax_id_data (list, optional):
The customer’s tax IDs. - test_clock (str, optional): ID of the test
clock to attach to the customer.

</div>

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

    cus_UXABX4zNYeDcJ9 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.v1.customers.post?
```

    def post(
        address:Unset=UNSET, balance:int=UNSET, business_name:str=UNSET, cash_balance:dict=UNSET, description:str=UNSET,
        email:str=UNSET, expand:list=UNSET, individual_name:str=UNSET, invoice_prefix:str=UNSET,
        invoice_settings:dict=UNSET, metadata:Unset=UNSET, name:str=UNSET, next_invoice_sequence:int=UNSET,
        payment_method:str=UNSET, phone:str=UNSET, preferred_locales:list=UNSET, shipping:Unset=UNSET, source:str=UNSET,
        tax:dict=UNSET, tax_exempt:str=UNSET, tax_id_data:list=UNSET, test_clock:str=UNSET
    ):

    Create a customer

    Parameters: ...

It also supports tab completion when filling in parameters!

### Complete API Coverage

FastStripe provides access to Stripe’s API through nested OpenAPI groups
generated from the pinned Stripe spec:

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

    Created product: New Product with ID: prod_UXAC1jJuFtyOx2

``` python
# Fetch existing resources
customers = await sapi.v1.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 = await sapi.v1.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
async for p in paged(sapi.v1.coupons.get, limit=5): break
print(f"Got {len(p.data)} coupons")
print(f"Has more pages: {p.has_more}")
```

    Got 5 coupons
    Has more pages: True

``` python
coupons = await pages(sapi.v1.coupons.get, limit=100)
len(coupons), coupons[0]
```

    (588, Coupon(id=ioULYkUY))

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

- **[`paged()`](https://AnswerDotAI.github.io/faststripe/core.html#paged)**:
  Async generator that yields each page from a resource API
- **[`pages()`](https://AnswerDotAI.github.io/faststripe/core.html#pages)**:
  Fetches all pages and returns the collected items

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

## Handling Webhooks

Stripe signs webhook payloads so your app can reject fake or modified
events. FastStripe provided the `parse_webhook(req)` helper for this
which returns a FastStripe Event object.

In a webhook route, `parse_webhook()` verifies the signature before
returning the event object:

``` python
# Example inside a FastHTML/FastAPI-style route
@rt
async def webhook(req):
    'Handle incoming webhooks from stripe'
    evt = await sapi.parse_webhook(req)
    print(evt, evt.data)
```

For lower-level integrations, use
[`verify_webhook()`](https://AnswerDotAI.github.io/faststripe/core.html#verify_webhook)
directly with the raw payload, Stripe signature header, and webhook
secret. `parse_webhook()` is usually the nicer path because it verifies
the event and converts nested Stripe data into FastStripe objects.
