Stigg Python API Library

https://github.com/stiggio/stigg-python
Admin
The Stigg Python API library provides convenient access to the Stigg REST API from any Python 3.9+...
Tokens:27,182
Snippets:193
Trust Score:6.7
License:Apache-2.0
Update:8 months ago
Show doc for...
Tokens:
Raw
### Add and Run Examples

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Demonstrates how to add and run example Python scripts. First, make the example script executable, then run it against your API.

```python
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
# ... your example code ...
```

```shell
# Make the example script executable
chmod +x examples/<your-example>.py

# Run the example against your api
./examples/<your-example>.py
```

--------------------------------

### Install Dependencies with Rye

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Installs project dependencies using Rye. This command synchronizes all features, ensuring all necessary packages are available for development.

```shell
#!/bin/sh
# Install dependencies using Rye
rye sync --all-features
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Installs project dependencies using pip. This command reads the development requirements from the `requirements-dev.lock` file.

```shell
# Install dependencies using pip
pip install -r requirements-dev.lock
```

--------------------------------

### Install Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Installs the Stigg Python SDK using pip. An optional extra for improved async performance with aiohttp can also be installed.

```bash
pip install --pre stigg

# For improved async performance with aiohttp
pip install --pre stigg[aiohttp]
```

--------------------------------

### Install from Git

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Installs the Stigg Python package directly from a Git repository using pip. This is useful for installing the latest development version.

```shell
# Install the package from Git
pip install git+ssh://git@github.com/stiggio/stigg-python.git
```

--------------------------------

### Build and Install Wheel File

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Builds a distributable wheel file for the Stigg Python package and then installs it using pip. This creates an efficient installation package.

```shell
# Build the distributable wheel file
rye build
# or
python -m build

# Install the wheel file
pip install ./path-to-wheel-file.whl
```

--------------------------------

### Install Stigg with aiohttp Support

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Installs the Stigg Python library with optional support for `aiohttp` for improved asynchronous concurrency performance.

```sh
pip install '--pre stigg[aiohttp]'
```

--------------------------------

### Install Stigg Python Library

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Installs the Stigg Python library from PyPI. It is recommended to use '--pre' for the latest pre-release versions.

```sh
pip install '--pre stigg'
```

--------------------------------

### Archive and Unarchive Customers (Stigg Python SDK)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Provides examples of how to archive and then unarchive a customer using the Stigg Python SDK to manage their lifecycle.

```python
from stigg import Stigg

client = Stigg()

# Archive a customer
archived = client.v1.customers.archive("customer-acme-corp")
print(f"Archived: {archived.data.id}")

# Unarchive the customer
restored = client.v1.customers.unarchive("customer-acme-corp")
print(f"Restored: {restored.data.id}")
```

--------------------------------

### Async Stigg Client with aiohttp (Python)

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Demonstrates using the asynchronous Stigg client with `aiohttp` as the HTTP backend. This requires installing `aiohttp` and instantiating the client with `DefaultAioHttpClient()`.

```python
import os
import asyncio
from stigg import DefaultAioHttpClient
from stigg import AsyncStigg


async def main() -> None:
    async with AsyncStigg(
        api_key=os.environ.get("STIGG_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        customer_response = await client.v1.customers.retrieve(
            "REPLACE_ME",
        )
        print(customer_response.data)


asyncio.run(main())
```

--------------------------------

### GET /api/v1/products

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Retrieves a list of all products. Supports pagination and filtering via query parameters.

```APIDOC
## GET /api/v1/products

### Description
Retrieves a paginated list of products. Supports filtering and sorting via query parameters.

### Method
GET

### Endpoint
/api/v1/products

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of products to return per page.
- **offset** (integer) - Optional - The number of products to skip before returning results.
- **sort_by** (string) - Optional - The field to sort the products by (e.g., 'name', 'created_at').
- **order** (string) - Optional - The sort order ('asc' or 'desc').

### Response
#### Success Response (200)
- **products** (array) - A list of product objects.
- **next_cursor** (string) - A cursor for fetching the next page of results.

#### Response Example
```json
{
  "products": [
    {
      "id": "prod_123abc",
      "name": "Example Product 1",
      "price": 19.99
    },
    {
      "id": "prod_456def",
      "name": "Example Product 2",
      "price": 29.99
    }
  ],
  "next_cursor": "cursor_xyz789"
}
```
```

--------------------------------

### Publish to PyPI Manually

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Provides instructions for manually publishing the Stigg Python package to PyPI. This involves setting the `PYPI_TOKEN` environment variable and running a publish script.

```shell
# Publish to PyPI manually
# Ensure PYPI_TOKEN is set in your environment
bin/publish-pypi
```

--------------------------------

### Run Tests

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Executes the test suite for the Stigg Python project. This script runs all defined tests to ensure code quality and functionality.

```shell
# Run the test suite
./scripts/test
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Activates the Python virtual environment. Once activated, you can run Python scripts directly without needing to prefix them with `rye run`.

```shell
# Activate the virtual environment
source .venv/bin/activate

# Now you can run Python scripts directly
python script.py
```

--------------------------------

### Lint and Format Code

Source: https://github.com/stiggio/stigg-python/blob/main/CONTRIBUTING.md

Commands for linting and formatting the Python code using Ruff and Black. The `lint` script checks for code style issues, while `format` automatically fixes them.

```shell
# Lint the code
./scripts/lint

# Format and fix all ruff issues automatically
./scripts/format
```

--------------------------------

### Configuring Default Timeout

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Explains how to set a default timeout for all API requests. This example configures all requests to time out after 20 seconds, overriding the default 1-minute timeout.

```python
from stigg import Stigg

# Configure the default for all requests:
client = Stigg(
    # 20 seconds (default is 1 minute)
    timeout=20.0,
)
```

--------------------------------

### Using Nested Parameters

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Illustrates how to pass nested parameters in API requests using dictionaries, which are typed as `TypedDict` for better editor support. This example shows a basic usage for filtering customers by creation date.

```python
from stigg import Stigg

client = Stigg()

page = client.v1.customers.list(
    created_at={},
)
print(page.data)
```

--------------------------------

### Determine Installed Stigg Python Version

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

This snippet shows how to import the stigg library and print its installed version. It's useful for verifying upgrades or debugging version conflicts in your Python environment. No external dependencies are required beyond the stigg library itself.

```python
import stigg
print(stigg.__version__)
```

--------------------------------

### Report Usage for Metered Billing with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Submits usage measurements for metered billing features, supporting bulk reporting. Requires the 'stigg' and 'datetime' libraries. This example shows how to report a single usage event for a customer and feature, including dimensions.

```python
from stigg import Stigg
from datetime import datetime

client = Stigg()

# Report single usage
usage_report = client.v1.usage.report(
    usages=[
        {
            "customerId": "customer-acme-corp",
            "featureId": "feature-api-calls",
            "value": 1500,
            "updateBehavior": "DELTA",  # Add to existing usage
            "dimensions": {
                "endpoint": "/api/v1/data",
                "method": "GET"
            }
        }
    ]
)

```

--------------------------------

### Initialize Stigg Clients (Sync and Async)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Demonstrates how to initialize both synchronous and asynchronous Stigg clients using an API key. It also shows usage of the synchronous client within a context manager for automatic resource cleanup.

```python
import os
from stigg import Stigg, AsyncStigg

# Synchronous client
client = Stigg(
    api_key=os.environ.get("STIGG_API_KEY"),
    timeout=60.0,  # default is 60 seconds
    max_retries=2,  # default retry count
)

# Asynchronous client
async_client = AsyncStigg(
    api_key=os.environ.get("STIGG_API_KEY"),
)

# Using context manager for automatic resource cleanup
with Stigg() as client:
    customer = client.v1.customers.retrieve("customer-123")
    print(customer.data)
```

--------------------------------

### Provision New Customer (Stigg Python SDK)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Shows how to provision a new customer using the Stigg Python SDK, including setting their ID, name, email, metadata, integrations, and an optional coupon.

```python
from stigg import Stigg

client = Stigg()

# Create a new customer with full configuration
customer = client.v1.customers.provision(
    id="customer-acme-corp",
    name="Acme Corporation",
    email="billing@acme.com",
    metadata={
        "industry": "technology",
        "company_size": "enterprise"
    },
    integrations=[
        {
            "id": "stripe-integration-id",
            "vendorIdentifier": "STRIPE",
            "syncedEntityId": "cus_stripe123"
        }
    ],
    coupon_id="coupon-welcome-20"
)

print(f"Created customer: {customer.data.id}")
# Output: Created customer: customer-acme-corp
```

--------------------------------

### Manage Products with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Demonstrates how to update, duplicate, archive, and unarchive products using the Stigg Python SDK. This requires an initialized Stigg client.

```python
client.v1.products.update_product(
    "product-saas-platform",
    display_name="SaaS Platform Pro"
)

duplicate = client.v1.products.duplicate_product(
    path_id="product-saas-platform",
    id="product-saas-platform-staging",
    display_name="SaaS Platform (Staging)"
)

client.v1.products.archive_product("product-deprecated")
client.v1.products.unarchive_product("product-deprecated")
```

--------------------------------

### Create and List Addons

Source: https://context7.com/stiggio/stigg-python/llms.txt

Creates purchasable addons that extend plan functionality and lists existing addons. Requires addon ID, display name, description, and product ID for creation. The list function supports pagination.

```python
from stigg import Stigg

client = Stigg()

# Create addon
addon = client.v1.events.addons.create_addon(
    id="addon-extra-storage",
    display_name="Extra Storage",
    description="Additional 100GB storage",
    product_id="product-saas-main"
)

print(f"Created addon: {addon.data.id}")

# List addons
for addon in client.v1.events.addons.list_addons(limit=20):
    print(f"Addon: {addon.id} - {addon.display_name}")

# Publish addon draft
published = client.v1.events.addons.publish_addon(
    "addon-extra-storage",
    publish_type="IMMEDIATELY"
)
```

--------------------------------

### Create and List Products

Source: https://context7.com/stiggio/stigg-python/llms.txt

Creates and manages products, which serve as containers for plans and features. Allows creating new products with an ID, display name, and description, and listing existing products with pagination.

```python
from stigg import Stigg

client = Stigg()

# Create product
product = client.v1.products.create_product(
    id="product-saas-platform",
    display_name="SaaS Platform",
    description="Main SaaS product offering"
)

# List products
for product in client.v1.products.list_products(limit=20):
    print(f"Product: {product.id} - {product.display_name}")
```

--------------------------------

### List Customers with Pagination (Stigg Python SDK)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Illustrates how to list customers using the Stigg Python SDK, demonstrating both automatic pagination via iteration and manual control over pagination using limit and next page retrieval.

```python
from stigg import Stigg

client = Stigg()

# Auto-paginating iterator
all_customers = []
for customer in client.v1.customers.list(limit=30):
    all_customers.append(customer)
    print(f"Customer: {customer.id} - {customer.name}")

# Manual pagination control
first_page = client.v1.customers.list(limit=30)
print(f"Total on first page: {len(first_page.data)}")

if first_page.has_next_page():
    next_page = first_page.get_next_page()
    print(f"Next page cursor: {first_page.pagination.next}")
```

--------------------------------

### POST /api/v1/products

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Creates a new product. Requires detailed parameters to define the product's attributes and configuration.

```APIDOC
## POST /api/v1/products

### Description
Creates a new product with the specified parameters.

### Method
POST

### Endpoint
/api/v1/products

#### Request Body
- **params** (object) - Required - An object containing the parameters for creating the product. Refer to `stigg.types.v1.product_create_product_params` for detailed schema.

### Request Example
```json
{
  "name": "New Gadget",
  "description": "A revolutionary new gadget.",
  "price": 99.99
}
```

### Response
#### Success Response (200)
- **product** (object) - Details of the newly created product, including its ID and configuration.

#### Response Example
```json
{
  "product": {
    "id": "prod_456def",
    "name": "New Gadget",
    "description": "A revolutionary new gadget.",
    "price": 99.99
  }
}
```
```

--------------------------------

### Provision New Subscription with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Creates a new subscription for a customer, specifying the plan, billing period, quantity, addons, billing information, trial configuration, and metadata. Requires the 'stigg' library. It returns the ID and status of the newly provisioned subscription.

```python
from stigg import Stigg

client = Stigg()

subscription = client.v1.subscriptions.provision(
    customer_id="customer-acme-corp",
    plan_id="plan-pro-monthly",
    billing_period="MONTHLY",
    unit_quantity=10,
    addons=[
        {"addonId": "addon-extra-storage", "quantity": 5},
        {"addonId": "addon-priority-support", "quantity": 1}
    ],
    billing_information={
        "billingAddress": {
            "line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "94102",
            "country": "US"
        },
        "taxIds": [
            {"type": "VAT", "value": "DE123456789"}
        ]
    },
    trial_override_configuration={
        "isTrial": True,
        "trialEndBehavior": "CONVERT_TO_PAID"
    },
    metadata={
        "source": "website",
        "campaign": "summer-2024"
    }
)

print(f"Subscription ID: {subscription.data.id}")
print(f"Status: {subscription.data.status}")
```

--------------------------------

### Get Usage History

Source: https://context7.com/stiggio/stigg-python/llms.txt

Retrieve historical usage data for a specific customer and feature. The response contains a list of usage records, each with a timestamp and value. Requires customer_id and feature_id.

```python
from stigg import Stigg

client = Stigg()

history = client.v1.usage.history(
    customer_id="customer-acme-corp",
    feature_id="feature-api-calls"
)

for record in history.data:
    print(f"Date: {record.timestamp}, Value: {record.value}")
```

--------------------------------

### Create Percentage and Fixed Amount Coupons

Source: https://context7.com/stiggio/stigg-python/llms.txt

Creates discount coupons with either a percentage off or a fixed amount off for a specified duration. Supports multiple currencies for fixed amounts and metadata for tracking.

```python
from stigg import Stigg

client = Stigg()

# Percentage discount coupon
percent_coupon = client.v1.coupons.create(
    id="coupon-summer-sale",
    name="Summer Sale 20% Off",
    description="20% discount for summer promotion",
    percent_off=20.0,
    duration_in_months=3,
    metadata={
        "campaign": "summer-2024",
        "source": "marketing"
    },
    amounts_off=None
)

# Fixed amount discount coupon
fixed_coupon = client.v1.coupons.create(
    id="coupon-10-off-usd",
    name="$10 Off",
    description="$10 discount in USD",
    percent_off=None,
    amounts_off=[
        {"amount": 10.0, "currency": "usd"},
        {"amount": 9.0, "currency": "eur"}
    ],
    duration_in_months=1,
    metadata=None
)

print(f"Created coupon: {percent_coupon.id}")
```

--------------------------------

### Create Pricing Plan

Source: https://context7.com/stiggio/stigg-python/llms.txt

Defines a new pricing plan with associated entitlements and configuration. Requires plan ID, display name, description, and product ID. Returns the created plan's data, including its ID.

```python
from stigg import Stigg

client = Stigg()

plan = client.v1.events.plans.create(
    id="plan-pro-monthly",
    display_name="Pro Plan",
    description="Professional tier with advanced features",
    product_id="product-saas-main"
)

print(f"Created plan: {plan.data.id}")
```

--------------------------------

### Retrieve Subscription by ID - Python

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Retrieves a specific subscription by its unique identifier. This method corresponds to the GET /api/v1/subscriptions/{id} API endpoint. It returns a Subscription object.

```python
client.v1.subscriptions.retrieve(id) -> Subscription
```

--------------------------------

### Per-Request HTTP Client Configuration in Python

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Illustrates how to override HTTP client options, such as proxy settings, on a per-request basis using the `with_options` method. This allows for flexible configuration without modifying the main client instance.

```python
from stigg import Stigg, DefaultHttpxClient

client = Stigg()

# Configure HTTP client options for a specific request
client.with_options(http_client=DefaultHttpxClient(proxy="http://another.proxy.example.com"))

```

--------------------------------

### List Subscriptions - Python

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Retrieves a list of subscriptions, optionally with filtering parameters. This method corresponds to the GET /api/v1/subscriptions API endpoint. It returns a paginated list of SubscriptionListResponse objects.

```python
client.v1.subscriptions.list(**params) -> SyncMyCursorIDPage[SubscriptionListResponse]
```

--------------------------------

### Preview Subscription Provisioning - Python

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Previews the result of provisioning a subscription without actually creating it. This method corresponds to the POST /api/v1/subscriptions/preview API endpoint. It accepts preview parameters and returns a SubscriptionPreviewResponse.

```python
client.v1.subscriptions.preview(**params) -> SubscriptionPreviewResponse
```

--------------------------------

### Synchronous Stigg Client Usage (Python)

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Demonstrates how to initialize and use the synchronous Stigg client in Python. It retrieves customer data using an API key, recommending the use of environment variables for security.

```python
import os
from stigg import Stigg

client = Stigg(
    api_key=os.environ.get("STIGG_API_KEY"),  # This is the default and can be omitted
)

customer_response = client.v1.customers.retrieve(
    "REPLACE_ME",
)
print(customer_response.data)
```

--------------------------------

### Asynchronous Stigg Client Usage (Python)

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Shows how to initialize and use the asynchronous Stigg client in Python with `asyncio`. It retrieves customer data asynchronously, similar to the synchronous client but requiring `await`.

```python
import os
import asyncio
from stigg import AsyncStigg

client = AsyncStigg(
    api_key=os.environ.get("STIGG_API_KEY"),  # This is the default and can be omitted
)


async def main() -> None:
    customer_response = await client.v1.customers.retrieve(
        "REPLACE_ME",
    )
    print(customer_response.data)


asyncio.run(main())
```

--------------------------------

### Async Client Usage with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Illustrates using the asynchronous Stigg client for high-concurrency applications. It shows standard async operations and high-performance async with aiohttp, requiring `asyncio` and `stigg` libraries.

```python
import asyncio
from stigg import AsyncStigg, DefaultAioHttpClient

async def main():
    # Standard async client with httpx
    async with AsyncStigg() as client:
        # Fetch customer
        customer = await client.v1.customers.retrieve("customer-acme-corp")
        print(f"Customer: {customer.data.name}")

        # Async pagination
        async for subscription in client.v1.subscriptions.list(limit=30):
            print(f"Subscription: {subscription.id}")

    # High-performance async with aiohttp
    async with AsyncStigg(http_client=DefaultAioHttpClient()) as client:
        tasks = [
            client.v1.customers.retrieve("customer-1"),
            client.v1.customers.retrieve("customer-2"),
            client.v1.customers.retrieve("customer-3"),
        ]
        results = await asyncio.gather(*tasks)
        for result in results:
            print(f"Fetched: {result.data.id}")

asyncio.run(main())
```

--------------------------------

### Configure HTTP Client with Proxies and Transports in Python

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Demonstrates how to configure the underlying `httpx` client for the Stigg client, including setting proxies and custom transports. This allows for advanced network configurations like routing through a proxy server.

```python
import httpx
from stigg import Stigg, DefaultHttpxClient

client = Stigg(
    # Alternatively, use the `STIGG_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

```

--------------------------------

### Preview Subscription Changes with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Allows previewing pricing and proration for potential subscription changes before committing. Requires the 'stigg' library. It outputs the total estimated cost and proration amount.

```python
from stigg import Stigg

client = Stigg()

preview = client.v1.subscriptions.preview(
    customer_id="customer-acme-corp",
    plan_id="plan-enterprise-annual",
    billing_period="ANNUALLY"
)

print(f"Preview total: {preview.total}")
print(f"Proration amount: {preview.proration}")
```

--------------------------------

### List Customer Resources with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Retrieves resources associated with a customer, useful for managing multi-instance subscriptions. Requires the 'stigg' library. It iterates through the resources and prints their IDs.

```python
from stigg import Stigg

client = Stigg()

for resource in client.v1.customers.list_resources("customer-acme-corp", limit=20):
    print(f"Resource: {resource.id}")
```

--------------------------------

### List and Retrieve Plans

Source: https://context7.com/stiggio/stigg-python/llms.txt

Queries and retrieves pricing plans from the product catalog. The list function allows pagination with a limit parameter, and retrieve fetches details for a specific plan by its ID.

```python
from stigg import Stigg

client = Stigg()

# List all plans
for plan in client.v1.events.plans.list(limit=20):
    print(f"Plan: {plan.id} - {plan.display_name}")

# Retrieve specific plan
plan = client.v1.events.plans.retrieve("plan-pro-monthly")
print(f"Plan details: {plan.data.display_name}")
```

--------------------------------

### Create Product - Python

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Creates a new product with the provided parameters. This method is part of the Products API and returns a ProductCreateProductResponse.

```python
from stigg.types.v1 import ProductCreateProductResponse
from stigg.types.v1.product_create_product_params import ProductCreateParams

# Assuming 'client' is an initialized Stigg client instance
params: ProductCreateParams = {
    "name": "New Product",
    "description": "A description for the new product"
}
response: ProductCreateProductResponse = client.v1.products.create_product(**params)
```

--------------------------------

### PromotionalEntitlements API

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Endpoints for managing promotional entitlements for customers, including creation, listing, and revocation.

```APIDOC
## POST /api/v1/customers/{id}/promotional-entitlements

### Description
Creates a promotional entitlement for a customer.

### Method
POST

### Endpoint
/api/v1/customers/{id}/promotional-entitlements

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.
#### Request Body
- **params** (object) - Required - An object containing the details for the promotional entitlement.

### Response
#### Success Response (200)
- **PromotionalEntitlementCreateResponse** (object) - The response object detailing the created promotional entitlement.

#### Response Example
```json
{
  "example": "PromotionalEntitlementCreateResponse object"
}
```

## GET /api/v1/customers/{id}/promotional-entitlements

### Description
Lists all promotional entitlements for a customer.

### Method
GET

### Endpoint
/api/v1/customers/{id}/promotional-entitlements

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering and pagination.

### Response
#### Success Response (200)
- **SyncMyCursorIDPage[PromotionalEntitlementListResponse]** (object) - A paginated list of promotional entitlements.

#### Response Example
```json
{
  "example": "SyncMyCursorIDPage[PromotionalEntitlementListResponse] object"
}
```

## DELETE /api/v1/customers/{id}/promotional-entitlements/{featureId}

### Description
Revokes a promotional entitlement for a customer.

### Method
DELETE

### Endpoint
/api/v1/customers/{id}/promotional-entitlements/{featureId}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.
- **featureId** (string) - Required - The unique identifier of the feature for which to revoke the entitlement.

### Response
#### Success Response (200)
- **PromotionalEntitlementRevokeResponse** (object) - The response object detailing the revoked promotional entitlement.

#### Response Example
```json
{
  "example": "PromotionalEntitlementRevokeResponse object"
}
```
```

--------------------------------

### Plans API

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Manage pricing plans, including creating, retrieving, and listing plans.

```APIDOC
## POST /api/v1/plans

### Description
Creates a new pricing plan.

### Method
POST

### Endpoint
/api/v1/plans

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating the plan.

### Response
#### Success Response (200)
- **PlanCreateResponse** (object) - The response object for creating a plan.

### Request Example
```json
{
  "name": "Basic Plan",
  "price": 10.00
}
```

### Response Example
```json
{
  "id": "plan_id_1",
  "name": "Basic Plan"
}
```

## GET /api/v1/plans/{id}

### Description
Retrieves details of a specific pricing plan.

### Method
GET

### Endpoint
/api/v1/plans/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the plan to retrieve.

### Response
#### Success Response (200)
- **PlanRetrieveResponse** (object) - The response object containing plan details.

### Response Example
```json
{
  "id": "plan_id_1",
  "name": "Basic Plan",
  "price": 10.00
}
```

## GET /api/v1/plans

### Description
Lists all pricing plans, with optional filtering and pagination.

### Method
GET

### Endpoint
/api/v1/plans

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering and pagination.

### Response
#### Success Response (200)
- **SyncMyCursorIDPage[PlanListResponse]** (object) - A paginated list of plans.

### Response Example
```json
{
  "data": [
    {
      "id": "plan_1",
      "name": "Basic Plan"
    },
    {
      "id": "plan_2",
      "name": "Premium Plan"
    }
  ],
  "next_cursor": "cursor_string"
}
```
```

--------------------------------

### Retrieve Customer Details (Stigg Python SDK)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Demonstrates fetching detailed information for a specific customer using their ID with the Stigg Python SDK. Includes error handling for 'not found' and general API errors.

```python
from stigg import Stigg
import stigg

client = Stigg()

try:
    customer = client.v1.customers.retrieve("customer-acme-corp")
    print(f"Customer: {customer.data.name}")
    print(f"Email: {customer.data.email}")
    print(f"Created: {customer.data.created_at}")
except stigg.NotFoundError:
    print("Customer not found")
except stigg.APIError as e:
    print(f"API error: {e.status_code}")
```

--------------------------------

### Raw Response Access with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Demonstrates accessing raw HTTP response data, including headers and streaming responses, using the Stigg Python SDK. This allows inspection of metadata like request IDs and iteration over streaming data. Requires the `stigg` library.

```python
from stigg import Stigg

client = Stigg()

# Access response headers
response = client.v1.customers.with_raw_response.retrieve("customer-acme-corp")
print(f"Request ID: {response.headers.get('x-request-id')}")
customer = response.parse()

# Streaming response for large payloads
with client.v1.customers.with_streaming_response.retrieve("customer-acme-corp") as response:
    for line in response.iter_lines():
        print(line)
```

--------------------------------

### Create Promotional Entitlement V1

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Creates a promotional entitlement for a customer using their ID and entitlement parameters. Returns a PromotionalEntitlementCreateResponse.

```python
client.v1.customers.promotional_entitlements.create(id, **params) -> PromotionalEntitlementCreateResponse
```

--------------------------------

### Provision Subscription - Python

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Provisions a new subscription. This method maps to the POST /api/v1/subscriptions API endpoint. It accepts provisioning parameters and returns a SubscriptionProvisionResponse.

```python
client.v1.subscriptions.provision(**params) -> SubscriptionProvisionResponse
```

--------------------------------

### List Subscriptions with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Retrieves a list of all subscriptions, with optional filtering capabilities. Requires the 'stigg' library. It iterates through the subscriptions and prints their IDs and plan IDs.

```python
from stigg import Stigg

client = Stigg()

for subscription in client.v1.subscriptions.list(limit=50):
    print(f"Subscription: {subscription.id} - Plan: {subscription.plan_id}")
```

--------------------------------

### Update Customer Information (Stigg Python SDK)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Shows how to update an existing customer's details, such as name, email, and metadata, using the Stigg Python SDK.

```python
from stigg import Stigg

client = Stigg()

updated_customer = client.v1.customers.update(
    "customer-acme-corp",
    name="Acme Corporation Inc.",
    email="new-billing@acme.com",
    metadata={
        "industry": "technology",
        "company_size": "enterprise",
        "tier": "platinum"
    }
)

print(f"Updated customer: {updated_customer.data.name}")
```

--------------------------------

### Retrieve Subscription Details with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Fetches detailed information for a specific subscription using its ID. Requires the 'stigg' library. It outputs the plan ID, status, and current period end date of the subscription.

```python
from stigg import Stigg

client = Stigg()

subscription = client.v1.subscriptions.retrieve("subscription-xyz-123")

print(f"Plan: {subscription.plan.id}")
print(f"Status: {subscription.status}")
print(f"Current period end: {subscription.current_period_end}")
```

--------------------------------

### Manage Plans with Stigg Python SDK

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

This snippet details the management of plans using the Stigg Python SDK. It provides methods for creating, retrieving, and listing plans. The implementation requires the Stigg SDK and corresponding plan-related type definitions.

```python
from stigg.types.v1.events import PlanCreateResponse, PlanRetrieveResponse, PlanListResponse

# Example usage (assuming 'client' is an initialized Stigg client instance)

# Create a plan
# response: PlanCreateResponse = client.v1.events.plans.create(**params)

# Retrieve a plan
# response: PlanRetrieveResponse = client.v1.events.plans.retrieve(id='plan_id')

# List plans
# response: SyncMyCursorIDPage[PlanListResponse] = client.v1.events.plans.list(**params)
```

--------------------------------

### Attach Payment Method to Customer (Stigg Python SDK)

Source: https://context7.com/stiggio/stigg-python/llms.txt

Demonstrates how to attach a payment method to a customer using their ID and the payment method's ID with the Stigg Python SDK, typically for subscription billing.

```python
from stigg import Stigg

client = Stigg()

customer = client.v1.customers.payment_method.attach(
    "customer-acme-corp",
    payment_method_id="pm_stripe_card_123"
)

print(f"Payment method attached to: {customer.data.id}")
```

--------------------------------

### Create Coupon (Python)

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Creates a new coupon with specified parameters. This method is used for coupon generation and requires parameters defining the coupon's properties. It returns the created Coupon object.

```python
from stigg.types.v1 import Coupon

# Assuming 'client' is an initialized Stigg client instance
# response: Coupon = client.v1.coupons.create(**params)
```

--------------------------------

### Manage Addons with Stigg Python SDK

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

This snippet demonstrates how to interact with the Stigg API for managing addons. It covers creating, retrieving, updating, archiving, and publishing addons. Dependencies include the Stigg SDK and specific type definitions for request and response objects.

```python
from stigg.types.v1.events import (
    AddonArchiveAddonResponse,
    AddonCreateAddonResponse,
    AddonListAddonsResponse,
    AddonPublishAddonResponse,
    AddonRetrieveAddonResponse,
    AddonUpdateAddonResponse,
)

# Example usage (assuming 'client' is an initialized Stigg client instance)

# Archive an addon
# response: AddonArchiveAddonResponse = client.v1.events.addons.archive_addon(id='addon_id')

# Create an addon
# response: AddonCreateAddonResponse = client.v1.events.addons.create_addon(**params)

# List addons
# response: SyncMyCursorIDPage[AddonListAddonsResponse] = client.v1.events.addons.list_addons(**params)

# Publish an addon
# response: AddonPublishAddonResponse = client.v1.events.addons.publish_addon(id='addon_id', **params)

# Retrieve an addon
# response: AddonRetrieveAddonResponse = client.v1.events.addons.retrieve_addon(id='addon_id')

# Update an addon
# response: AddonUpdateAddonResponse = client.v1.events.addons.update_addon(id='addon_id', **params)
```

--------------------------------

### List Promotional Entitlements V1

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Lists promotional entitlements for a customer by their ID, with optional parameters for filtering. Returns a paginated list of PromotionalEntitlementListResponse objects.

```python
client.v1.customers.promotional_entitlements.list(id, **params) -> SyncMyCursorIDPage[PromotionalEntitlementListResponse]
```

--------------------------------

### Configuring Granular Timeouts

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Illustrates how to configure fine-grained timeout settings for different stages of an HTTP request (connect, read, write). This uses an `httpx.Timeout` object for more precise control over request timing.

```python
import httpx
from stigg import Stigg

client = Stigg(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)
```

--------------------------------

### POST /api/v1/products/{id}/unarchive

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Unarchives a previously archived product by its ID. This makes the product available for use again.

```APIDOC
## POST /api/v1/products/{id}/unarchive

### Description
Unarchives a product that was previously archived.

### Method
POST

### Endpoint
/api/v1/products/{id}/unarchive

#### Path Parameters
- **id** (string) - Required - The unique identifier of the product to unarchive.

### Request Example
```json
{
  "id": "prod_123abc"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the product has been unarchived.

#### Response Example
```json
{
  "message": "Product prod_123abc has been unarchived successfully."
}
```
```

--------------------------------

### Enable Stigg Logging in Shell

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Shows how to enable logging for the Stigg library in a shell environment. By setting the `STIGG_LOG` environment variable, you can control the verbosity of the logs. 'info' provides standard logging, while 'debug' offers more detailed output.

```shell
# Set logging level to info
export STIGG_LOG=info

# For more verbose logging, set to debug
# export STIGG_LOG=debug

```

--------------------------------

### Report and Retrieve Usage with Stigg Python SDK

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

This snippet demonstrates how to report and retrieve usage data using the Stigg Python SDK. It includes methods for reporting usage and fetching usage history for customers and features. Dependencies include the Stigg SDK and specific usage-related type definitions.

```python
from stigg.types.v1 import UsageHistoryResponse, UsageReportResponse

# Example usage (assuming 'client' is an initialized Stigg client instance)

# Get usage history
# response: UsageHistoryResponse = client.v1.usage.history(feature_id='feature_id', customer_id='customer_id', **params)

# Report usage
# response: UsageReportResponse = client.v1.usage.report(**params)
```

--------------------------------

### Iterate Through All Customers (Synchronous)

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Fetches all customers from the API by automatically handling pagination. This synchronous iterator fetches subsequent pages as needed, simplifying the process of retrieving large datasets.

```python
from stigg import Stigg

client = Stigg()

all_customers = []
# Automatically fetches more pages as needed.
for customer in client.v1.customers.list(
    limit=30,
):
    # Do something with customer here
    all_customers.append(customer)
print(all_customers)
```

--------------------------------

### Manage Coupons

Source: https://context7.com/stiggio/stigg-python/llms.txt

Retrieves, lists, updates, and archives coupons. Allows fetching a specific coupon by ID, listing all coupons with pagination, updating coupon details, and archiving expired or promotional coupons.

```python
from stigg import Stigg

client = Stigg()

# Retrieve coupon
coupon = client.v1.coupons.retrieve("coupon-summer-sale")
print(f"Coupon: {coupon.name} - {coupon.percent_off}% off")

# List all coupons
for coupon in client.v1.coupons.list(limit=20):
    print(f"Coupon: {coupon.id} - {coupon.name}")

# Update coupon
updated = client.v1.coupons.update_coupon(
    "coupon-summer-sale",
    description="Extended summer promotion - 20% discount"
)

# Archive coupon
archived = client.v1.coupons.archive_coupon("coupon-expired-promo")
print(f"Archived: {archived.id}")
```

--------------------------------

### Provision Customer V1

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Provisions a new customer with the specified parameters. This method returns the newly created CustomerResponse object.

```python
client.v1.customers.provision(**params) -> CustomerResponse
```

--------------------------------

### Addons API

Source: https://github.com/stiggio/stigg-python/blob/main/api.md

Manage addons, including creating, retrieving, updating, publishing, archiving, and managing drafts.

```APIDOC
## POST /api/v1/addons/{id}/archive

### Description
Archives a specific addon.

### Method
POST

### Endpoint
/api/v1/addons/{id}/archive

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the addon to archive.

### Response
#### Success Response (200)
- **AddonArchiveAddonResponse** (object) - The response object for archiving an addon.

### Request Example
```json
{
  "id": "addon_id_to_archive"
}
```

### Response Example
```json
{
  "message": "Addon archived successfully."
}
```

## POST /api/v1/addons

### Description
Creates a new addon.

### Method
POST

### Endpoint
/api/v1/addons

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating the addon.

### Response
#### Success Response (200)
- **AddonCreateAddonResponse** (object) - The response object for creating an addon.

### Request Example
```json
{
  "name": "New Addon",
  "description": "This is a new addon."
}
```

### Response Example
```json
{
  "id": "new_addon_id",
  "name": "New Addon"
}
```

## GET /api/v1/addons

### Description
Lists all addons, with optional filtering and pagination.

### Method
GET

### Endpoint
/api/v1/addons

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering and pagination.

### Response
#### Success Response (200)
- **SyncMyCursorIDPage[AddonListAddonsResponse]** (object) - A paginated list of addons.

### Response Example
```json
{
  "data": [
    {
      "id": "addon_1",
      "name": "Addon One"
    },
    {
      "id": "addon_2",
      "name": "Addon Two"
    }
  ],
  "next_cursor": "cursor_string"
}
```

## POST /api/v1/addons/{id}/publish

### Description
Publishes a specific addon.

### Method
POST

### Endpoint
/api/v1/addons/{id}/publish

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the addon to publish.
#### Request Body
- **params** (object) - Optional - Parameters for publishing the addon.

### Response
#### Success Response (200)
- **AddonPublishAddonResponse** (object) - The response object for publishing an addon.

### Request Example
```json
{
  "id": "addon_id_to_publish"
}
```

### Response Example
```json
{
  "message": "Addon published successfully."
}
```

## GET /api/v1/addons/{id}

### Description
Retrieves details of a specific addon.

### Method
GET

### Endpoint
/api/v1/addons/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the addon to retrieve.

### Response
#### Success Response (200)
- **AddonRetrieveAddonResponse** (object) - The response object containing addon details.

### Response Example
```json
{
  "id": "addon_id",
  "name": "Example Addon",
  "description": "Details about the example addon."
}
```

## PATCH /api/v1/addons/{id}

### Description
Updates an existing addon.

### Method
PATCH

### Endpoint
/api/v1/addons/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the addon to update.
#### Request Body
- **params** (object) - Required - The fields to update for the addon.

### Response
#### Success Response (200)
- **AddonUpdateAddonResponse** (object) - The response object for updating an addon.

### Request Example
```json
{
  "id": "addon_id_to_update",
  "description": "Updated description for the addon."
}
```

### Response Example
```json
{
  "id": "addon_id_to_update",
  "name": "Example Addon",
  "description": "Updated description for the addon."
}
```
```

--------------------------------

### Migrate Subscription to Different Plan with Stigg Python SDK

Source: https://context7.com/stiggio/stigg-python/llms.txt

Transfers a subscription from its current plan to a new plan, with options for proration. Requires the 'stigg' library. It confirms the plan ID of the migrated subscription.

```python
from stigg import Stigg

client = Stigg()

migrated = client.v1.subscriptions.migrate(
    "subscription-xyz-123",
    plan_id="plan-enterprise-monthly",
    billing_period="MONTHLY"
)

print(f"Migrated to plan: {migrated.plan.id}")
```

--------------------------------

### Manage HTTP Client Resources with a Context Manager in Python

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Shows how to manage the lifecycle of the Stigg HTTP client using a context manager (`with` statement). This ensures that the underlying HTTP connections are properly closed when exiting the block, preventing resource leaks.

```python
from stigg import Stigg

# Use Stigg client as a context manager
with Stigg() as client:
  # Make API requests within this block
  # client.v1.some_endpoint.some_method()
  pass

# HTTP client is now closed automatically

```

--------------------------------

### Manual Pagination Control

Source: https://github.com/stiggio/stigg-python/blob/main/README.md

Demonstrates granular control over API pagination using methods like `has_next_page()`, `next_page_info()`, and `get_next_page()`. This allows for custom logic when fetching paginated data, such as checking for more pages before proceeding.

```python
first_page = await client.v1.customers.list(
    limit=30,
)
if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.data)}")

# Remove `await` for non-async usage.
```

--------------------------------

### Manage Addon Drafts

Source: https://context7.com/stiggio/stigg-python/llms.txt

Handles draft versions of addons, allowing for creation and removal of drafts. This is useful for making modifications before publishing an addon.

```python
from stigg import Stigg

client = Stigg()

# Create a draft for modifications
draft = client.v1.events.addons.draft.create_addon_draft("addon-extra-storage")
print(f"Draft created for: {draft.data.id}")

# Remove draft if changes are not needed
removed = client.v1.events.addons.draft.remove_addon_draft("addon-extra-storage")
print(f"Draft removed: {removed.success}")
```

--------------------------------

### Sync Subscription Usage

Source: https://context7.com/stiggio/stigg-python/llms.txt

Synchronize usage data with the billing provider for a given subscription. Returns a success status. Requires a subscription ID.

```python
from stigg import Stigg

client = Stigg()

sync_result = client.v1.subscriptions.usage.sync("subscription-xyz-123")
print(f"Usage synced: {sync_result.success}")
```
Tokens:
Raw