### Install App Store Server Library

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/README.md

Use pip to install the base library. For asynchronous support, install with the `async` extra.

```bash
pip install app-store-server-library
```

```bash
# For async support
pip install app-store-server-library[async]
```

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

### Flask Application Setup with App Store Server Library

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

This Flask example demonstrates how to initialize the App Store Server API client and signed data verifier. It includes configuration for API keys, bundle IDs, and environment settings, and sets up routes for handling webhook notifications and retrieving transaction information.

```python
from flask import Flask, request, jsonify
from appstoreserverlibrary.api_client import AppStoreServerAPIClient, APIException
from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier, VerificationException
from appstoreserverlibrary.models.Environment import Environment

app = Flask(__name__)

# Configuration
CONFIG = {
    'SIGNING_KEY': b'...',  # Load from secure storage
    'KEY_ID': 'ABCDEFGHIJ',
    'ISSUER_ID': '99b16628-15e4-4668-972b-eeff55eeff55',
    'BUNDLE_ID': 'com.example.app',
    'ENVIRONMENT': Environment.PRODUCTION,
    'APP_APPLE_ID': 123456789,
    'ROOT_CERTIFICATES': [],  # Load from files
}

# Initialize clients
api_client = AppStoreServerAPIClient(
    signing_key=CONFIG['SIGNING_KEY'],
    key_id=CONFIG['KEY_ID'],
    issuer_id=CONFIG['ISSUER_ID'],
    bundle_id=CONFIG['BUNDLE_ID'],
    environment=CONFIG['ENVIRONMENT']
)

data_verifier = SignedDataVerifier(
    root_certificates=CONFIG['ROOT_CERTIFICATES'],
    enable_online_checks=True,
    environment=CONFIG['ENVIRONMENT'],
    bundle_id=CONFIG['BUNDLE_ID'],
    app_apple_id=CONFIG['APP_APPLE_ID']
)

@app.route('/webhook/notification', methods=['POST'])
def handle_notification():
    try:
        payload = request.json
        signed_payload = payload['signedPayload']
        
        # Verify and decode
        notification = data_verifier.verify_and_decode_notification(signed_payload)
        
        # Process notification
        print(f"Notification type: {notification.notificationType}")
        
        return {"status": "success"}
    
    except VerificationException as e:
        print(f"Verification failed: {e.status}")
        return {"status": "failed"}, 400
    except Exception as e:
        print(f"Error: {e}")
        return {"status": "error"}, 500

@app.route('/api/transactions/<transaction_id>', methods=['GET'])
def get_transaction(transaction_id):
    try:
        response = api_client.get_transaction_info(transaction_id)
        transaction = data_verifier.verify_and_decode_signed_transaction(
            response.signedTransactionInfo
        )
        
        return {
            "productId": transaction.productId,
            "purchaseDate": transaction.purchaseDate
        }
    
    except APIException as e:
        return {"error": str(e)}, e.http_status_code
    except VerificationException as e:
        return {"error": "Verification failed"}, 400

```

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

### Install Async App Store Server Library

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

Install the library with async support using pip. This is required for using the AsyncAppStoreServerAPIClient.

```bash
pip install app-store-server-library[async]
```

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

### AsyncAppStoreServerAPIClient Constructor

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Initializes the AsyncAppStoreServerAPIClient with necessary credentials and environment configuration. Requires httpx to be installed.

```APIDOC
## Constructor

```python
def __init__(self, signing_key: bytes, key_id: str, issuer_id: str, 
             bundle_id: str, environment: Environment) -> None
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| signing_key | bytes | Yes | — | The signing key obtained from App Store Connect (PEM-encoded) |
| key_id | str | Yes | — | The key identifier from App Store Connect |
| issuer_id | str | Yes | — | The issuer identifier (team ID) from App Store Connect |
| bundle_id | str | Yes | — | The bundle identifier of your app |
| environment | Environment | Yes | — | The server environment (PRODUCTION or SANDBOX) |

### Raises
- `ValueError`: If environment is XCODE or invalid
- `ImportError`: If httpx is not installed

### Example

```python
from appstoreserverlibrary.api_client import AsyncAppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment
import asyncio

async def main():
    # Read key from file
    with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
        signing_key = f.read()

    client = AsyncAppStoreServerAPIClient(
        signing_key=signing_key,
        key_id="ABCDEFGHIJ",
        issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",
        bundle_id="com.example.app",
        environment=Environment.SANDBOX
    )
    
    try:
        # Use the client
        response = await client.request_test_notification()
        print(response)
    finally:
        await client.async_close()

asyncio.run(main())
```
```

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

### Install the library using pip

Source: https://github.com/apple/app-store-server-library-python/blob/main/README.md

Installs the app-store-server-library package.

```sh
pip install app-store-server-library
```

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

### Initialize AsyncAppStoreServerAPIClient

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Instantiate the asynchronous client with your credentials and app details. Ensure httpx is installed. The client should be closed asynchronously when no longer needed.

```python
from appstoreserverlibrary.api_client import AsyncAppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment
import asyncio

async def main():
    # Read key from file
    with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
        signing_key = f.read()

    client = AsyncAppStoreServerAPIClient(
        signing_key=signing_key,
        key_id="ABCDEFGHIJ",
        issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",
        bundle_id="com.example.app",
        environment=Environment.SANDBOX
    )
    
    try:
        # Use the client
        response = await client.request_test_notification()
        print(response)
    finally:
        await client.async_close()

asyncio.run(main())
```

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

### Handle Rate Limit Errors

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/errors.md

Implement a loop to handle rate limit exceeded errors by backing off and retrying the API call. This example uses a fixed 60-second delay as a starting point.

```python
def call_with_rate_limit_handling(func):
    """Call API function with rate limit handling"""
    while True:
        try:
            return func()
        except APIException as e:
            if e.api_error == APIError.RATE_LIMIT_EXCEEDED:
                # Apple recommends exponential backoff
                print("Rate limited, backing off...")
                time.sleep(60)  # Start with 1 minute
            else:
                raise
```

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

### Django Settings and Service Configuration for App Store Library

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

This Django example shows how to configure the App Store Server Library in settings.py and create a service class for initializing the API client and verifier. It demonstrates loading signing keys and root certificates from specified file paths.

```python
# settings.py
APPLE_IN_APP = {
    'SIGNING_KEY_PATH': '/secure/SubscriptionKey_ABCDEFGHIJ.p8',
    'KEY_ID': 'ABCDEFGHIJ',
    'ISSUER_ID': '99b16628-15e4-4668-972b-eeff55eeff55',
    'BUNDLE_ID': 'com.example.app',
    'ENVIRONMENT': 'PRODUCTION',
    'APP_APPLE_ID': 123456789,
    'ROOT_CERTS_PATH': '/secure/apple_certs/',
}

# services.py
from django.conf import settings
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier
from appstoreserverlibrary.models.Environment import Environment

class AppStoreService:
    _api_client = None
    _verifier = None
    
    @classmethod
    def get_api_client(cls):
        if cls._api_client is None:
            config = settings.APPLE_IN_APP
            with open(config['SIGNING_KEY_PATH'], 'rb') as f:
                signing_key = f.read()
            
            environment = getattr(Environment, config['ENVIRONMENT'])
            cls._api_client = AppStoreServerAPIClient(
                signing_key=signing_key,
                key_id=config['KEY_ID'],
                issuer_id=config['ISSUER_ID'],
                bundle_id=config['BUNDLE_ID'],
                environment=environment
            )
        
        return cls._api_client
    
    @classmethod
    def get_verifier(cls):
        if cls._verifier is None:
            config = settings.APPLE_IN_APP
            
            # Load root certificates
            root_certs = []
            import os
            for filename in os.listdir(config['ROOT_CERTS_PATH']):
                if filename.endswith('.cer'):
                    with open(os.path.join(config['ROOT_CERTS_PATH'], filename), 'rb') as f:
                        root_certs.append(f.read())
            
            environment = getattr(Environment, config['ENVIRONMENT'])
            cls._verifier = SignedDataVerifier(
                root_certificates=root_certs,
                enable_online_checks=True,
                environment=environment,
                bundle_id=config['BUNDLE_ID'],
                app_apple_id=config['APP_APPLE_ID']
            )
        
        return cls._verifier

```

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

### API Usage Example

Source: https://github.com/apple/app-store-server-library-python/blob/main/README.md

Demonstrates how to initialize the AppStoreServerAPIClient and make a request for a test notification.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient, APIException
from appstoreserverlibrary.models.Environment import Environment

private_key = read_private_key("/path/to/key/SubscriptionKey_ABCDEFGHIJ.p8") # Implementation will vary

key_id = "ABCDEFGHIJ"
issuer_id = "99b16628-15e4-4668-972b-eeff55eeff55"
bundle_id = "com.example"
environment = Environment.SANDBOX

client = AppStoreServerAPIClient(private_key, key_id, issuer_id, bundle_id, environment)

try:
    response = client.request_test_notification()
    print(response)
except APIException as e:
    print(e)
```

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

### Complete App Store Server API Usage Example

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/RequestAndResponseModels.md

Demonstrates common operations using the App Store Server API client, including extending subscriptions, retrieving transaction history, and sending consumption information. Ensure necessary models and the API client are imported.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.ExtendRenewalDateRequest import ExtendRenewalDateRequest
from appstoreserverlibrary.models.ExtendReasonCode import ExtendReasonCode
from appstoreserverlibrary.models.TransactionHistoryRequest import TransactionHistoryRequest, ProductType
from appstoreserverlibrary.models.ConsumptionRequest import ConsumptionRequest
from appstoreserverlibrary.models.ConsumptionStatus import ConsumptionStatus
from appstoreserverlibrary.models.ConsumptionRequestReason import ConsumptionRequestReason
import uuid

client = AppStoreServerAPIClient(...)

# Extend subscription
extend_request = ExtendRenewalDateRequest(
    extendByDays=30,
    extendReasonCode=ExtendReasonCode.CUSTOMER_SATISFACTION
)
response = client.extend_subscription_renewal_date(
    original_transaction_id="123456789",
    extend_renewal_date_request=extend_request
)

# Get transaction history
history_request = TransactionHistoryRequest(
    productTypes=[ProductType.AUTO_RENEWABLE],
    revoked=False
)
history = client.get_transaction_history(
    any_transaction_id="123456789",
    revision=None,
    transaction_history_request=history_request
)

# Send consumption info
consumption_request = ConsumptionRequest(
    customerConsented=True,
    consumptionStatus=ConsumptionStatus.CONSUMED,
    appAccountToken=uuid.uuid4(),
    reason=ConsumptionRequestReason.GENERAL
)
client.send_consumption_information(
    transaction_id="123456789",
    consumption_request=consumption_request
)
```

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

### Use Async Support for App Store Server API in Python

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/README.md

Install the async extra and use AsyncAppStoreServerAPIClient for asynchronous operations. Remember to close the client after use.

```bash
pip install app-store-server-library[async]
```

```python
from appstoreserverlibrary.api_client import AsyncAppStoreServerAPIClient

client = AsyncAppStoreServerAPIClient(...)
response = await client.request_test_notification()
await client.async_close()
```

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

### Initiate Performance Test

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Starts a performance test for the App Store Server API. Requires a `PerformanceTestRequest` object with test parameters.

```python
async def initiate_performance_test(self, performance_test_request: PerformanceTestRequest) -> PerformanceTestResponse
```

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

### get_all_subscription_statuses

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets the statuses for all of a customer's subscriptions. Refer to AppStoreServerAPIClient.get_all_subscription_statuses for parameter details.

```APIDOC
## get_all_subscription_statuses

### Description
Gets the statuses for all of a customer's subscriptions.

### Method Signature
```python
async def get_all_subscription_statuses(self, any_transaction_id: str, status: Optional[List[Status]] = None) -> StatusResponse
```

### Parameters
See `AppStoreServerAPIClient.get_all_subscription_statuses` for parameter details.

### Returns
`StatusResponse`
```

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

### Verification Usage Example

Source: https://github.com/apple/app-store-server-library-python/blob/main/README.md

Shows how to set up and use the SignedDataVerifier to verify and decode a signed notification.

```python
from appstoreserverlibrary.models.Environment import Environment
from appstoreserverlibrary.signed_data_verifier import VerificationException, SignedDataVerifier

root_certificates = load_root_certificates()
enable_online_checks = True
bundle_id = "com.example"
environment = Environment.SANDBOX
app_apple_id = None # appAppleId must be provided for the Production environment
signed_data_verifier = SignedDataVerifier(root_certificates, enable_online_checks, environment, bundle_id, app_apple_id)

try:
    signed_notification = "ey.."
    payload = signed_data_verifier.verify_and_decode_notification(signed_notification)
    print(payload)
except VerificationException as e:
    print(e)
```

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

### Initiate Performance Test with App Store Server API Client

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Use this method to start a performance test for your real-time event handling. It requires a PerformanceTestRequest object and returns a PerformanceTestResponse.

```python
from appstoreserverlibrary.models.PerformanceTestRequest import PerformanceTestRequest

request = PerformanceTestRequest()

response = client.initiate_performance_test(performance_test_request=request)
print(f"Test ID: {response.requestId}")
```

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

### Handle VerificationException in Python

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/errors.md

Example of how to catch and handle VerificationException when verifying signed transactions. It checks the VerificationStatus to provide specific error messages and recovery advice.

```python
from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier, VerificationException, VerificationStatus

verifier = SignedDataVerifier(...)

try:
    transaction = verifier.verify_and_decode_signed_transaction(signed_data)
except VerificationException as e:
    if e.status == VerificationStatus.INVALID_SIGNATURE:
        print("Signature is invalid - possible tampering or expired certificate")
        print("Check root certificates are current")
    elif e.status == VerificationStatus.INVALID_ENVIRONMENT:
        print("Data is from wrong environment")
        print(f"Expected: {verifier._environment}")
    elif e.status == VerificationStatus.INVALID_APP_IDENTIFIER:
        print("Bundle ID or Apple ID mismatch")
        print("Check verifier configuration")
    elif e.status == VerificationStatus.INVALID_CERTIFICATE_CHAIN:
        print("Certificate chain is invalid")
        print("Update root certificates from Apple PKI")
    else:
        print(f"Verification failed: {e.status}")
```

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

### Get Configured Real-Time Event URL

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Retrieves the currently configured URL for receiving real-time events. This allows you to verify the endpoint.

```python
async def get_realtime_url(self) -> RealtimeUrlResponse
```

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

### Receipt Usage Example

Source: https://github.com/apple/app-store-server-library-python/blob/main/README.md

Demonstrates how to use ReceiptUtility to extract transaction IDs and retrieve transaction history using AppStoreServerAPIClient.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient, APIException, GetTransactionHistoryVersion
from appstoreserverlibrary.models.Environment import Environment
from appstoreserverlibrary.receipt_utility import ReceiptUtility
from appstoreserverlibrary.models.HistoryResponse import HistoryResponse
from appstoreserverlibrary.models.TransactionHistoryRequest import TransactionHistoryRequest, ProductType, Order

private_key = read_private_key("/path/to/key/SubscriptionKey_ABCDEFGHIJ.p8") # Implementation will vary

key_id = "ABCDEFGHIJ"
issuer_id = "99b16628-15e4-4668-972b-eeff55eeff55"
bundle_id = "com.example"
environment = Environment.SANDBOX

client = AppStoreServerAPIClient(private_key, key_id, issuer_id, bundle_id, environment)
receipt_util = ReceiptUtility()
app_receipt = "MI.."

try:
    transaction_id = receipt_util.extract_transaction_id_from_app_receipt(app_receipt)
    if transaction_id != None:
        transactions = []
        response: HistoryResponse = None
        request: TransactionHistoryRequest = TransactionHistoryRequest(
            sort=Order.ASCENDING,
            revoked=False,
            productTypes=[ProductType.AUTO_RENEWABLE]
        )
        while response == None or response.hasMore:
            revision = response.revision if response != None else None
            response = client.get_transaction_history(transaction_id, revision, request, GetTransactionHistoryVersion.V2)
            for transaction in response.signedTransactions:
                transactions.append(transaction)
        print(transactions)
except APIException as e:
    print(e)
```

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

### Handle API Errors

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/INDEX.md

Example of how to catch and handle API exceptions, including specific error codes like rate limits and general server errors.

```python
from appstoreserverlibrary.api_client import APIException, APIError

# Assuming 'client' is an instance of AppStoreServerAPIClient
try:
    response = client.get_transaction_history(...)
except APIException as e:
    if e.api_error == APIError.RATE_LIMIT_EXCEEDED:
        # Implement backoff
    elif e.http_status_code >= 500:
        # Server error, retry
```

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

### Get Real-time Event URL

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Retrieves the currently configured URL for receiving real-time events. The response contains the URL string.

```python
response = client.get_realtime_url()
print(f"URL: {response.url}")
```

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

### Get Transaction History Request

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/README.md

Demonstrates how to construct a TransactionHistoryRequest object and use it to fetch transaction history from the App Store Server API. Ensure the client is properly initialized before making the call.

```python
from appstoreserverlibrary.models.Status import Status
from appstoreserverlibrary.models.TransactionHistoryRequest import TransactionHistoryRequest, ProductType

request = TransactionHistoryRequest(
    productTypes=[ProductType.AUTO_RENEWABLE],
    revoked=False
)

response = client.get_transaction_history(
    any_transaction_id="123",
    revision=None,
    transaction_history_request=request
)
```

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

### Process App Receipt and Get Subscription Status

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/ReceiptUtility.md

This snippet demonstrates how to process an app receipt to extract a transaction ID, query the App Store Server API for subscription statuses, and verify the signed data. It's useful for understanding the current subscription state of a user.

```python
from appstoreserverlibrary.receipt_utility import ReceiptUtility
from appstoreserverlibrary.api_client import AppStoreServerAPIClient, GetTransactionHistoryVersion
from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier
from appstoreserverlibrary.models.Environment import Environment
from appstoreserverlibrary.models.TransactionHistoryRequest import TransactionHistoryRequest, ProductType

class ReceiptProcessor:
    def __init__(self, signing_key: bytes, key_id: str, issuer_id: str, 
                 bundle_id: str, root_certificates: list):
        self.receipt_utility = ReceiptUtility()
        self.api_client = AppStoreServerAPIClient(
            signing_key=signing_key,
            key_id=key_id,
            issuer_id=issuer_id,
            bundle_id=bundle_id,
            environment=Environment.PRODUCTION
        )
        self.verifier = SignedDataVerifier(
            root_certificates=root_certificates,
            enable_online_checks=True,
            environment=Environment.PRODUCTION,
            bundle_id=bundle_id,
            app_apple_id=123456789
        )
    
    def process_app_receipt(self, app_receipt: str) -> dict:
        """Process an app receipt and return subscription status"""
        
        try:
            # Step 1: Extract transaction ID from receipt (no verification)
            transaction_id = self.receipt_utility.extract_transaction_id_from_app_receipt(
                app_receipt
            )
            
            if not transaction_id:
                return {
                    "success": False,
                    "error": "Receipt contains no in-app purchases"
                }
            
            # Step 2: Query App Store Server API
            status_response = self.api_client.get_all_subscription_statuses(
                any_transaction_id=transaction_id
            )
            
            # Step 3: Verify and decode signed data
            subscriptions = []
            for subscription_status in status_response.data:
                for last_transaction in subscription_status.lastTransactions:
                    try:
                        # Verify each signed transaction
                        transaction = self.verifier.verify_and_decode_signed_transaction(
                            last_transaction.signedTransactionInfo
                        )
                        renewal_info = self.verifier.verify_and_decode_renewal_info(
                            last_transaction.signedRenewalInfo
                        )
                        
                        subscriptions.append({
                            "productId": transaction.productId,
                            "originalTransactionId": transaction.originalTransactionId,
                            "expirationDate": renewal_info.expirationDate,
                            "autoRenewStatus": renewal_info.autoRenewStatus
                        })
                    except Exception as e:
                        print(f"Failed to verify transaction: {e}")
                        continue
            
            return {
                "success": True,
                "subscriptions": subscriptions
            }
        
        except ValueError as e:
            return {
                "success": False,
                "error": f"Invalid receipt format: {e}"
            }
        except Exception as e:
            return {
                "success": False,
                "error": f"Failed to process receipt: {e}"
            }
    
    def get_transaction_history(self, app_receipt: str) -> dict:
        """Get complete transaction history for a receipt"""
        
        try:
            transaction_id = self.receipt_utility.extract_transaction_id_from_app_receipt(
                app_receipt
            )
            
            if not transaction_id:
                return {"success": False, "error": "No transactions in receipt"}
            
            # Query transaction history
            request = TransactionHistoryRequest(
                productTypes=[ProductType.AUTO_RENEWABLE],
                revoked=False
            )
            
            all_transactions = []
            revision = None
            
            while True:
                response = self.api_client.get_transaction_history(
                    any_transaction_id=transaction_id,
                    revision=revision,
                    transaction_history_request=request,
                    version=GetTransactionHistoryVersion.V2
                )
                
                # Verify all transactions

```

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

### Initialize AppStoreServerAPIClient

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Instantiate the client with your signing key, key ID, issuer ID, bundle ID, and the target environment. Ensure the signing key is read from a PEM-encoded private key file.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment

# Read key from file
with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
    signing_key = f.read()

client = AppStoreServerAPIClient(
    signing_key=signing_key,
    key_id="ABCDEFGHIJ",
    issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",
    bundle_id="com.example.app",
    environment=Environment.SANDBOX
)
```

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

### Get Refund History (Python)

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Retrieves a paginated list of a customer's refunded in-app purchases. Use the revision token for subsequent calls to get the next page of results.

```python
response = client.get_refund_history(any_transaction_id="123456789", revision=None)
for signed_transaction in response.signedTransactions:
    print(signed_transaction)
```

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

### Get Transaction History (Python)

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Retrieves a paginated list of a customer's in-app purchase transaction history. Use the revision token for subsequent calls to get the next page of results.

```python
from appstoreserverlibrary.models.TransactionHistoryRequest import TransactionHistoryRequest, ProductType, Order
from appstoreserverlibrary.api_client import GetTransactionHistoryVersion

request = TransactionHistoryRequest(
    productTypes=[ProductType.AUTO_RENEWABLE],
    sort=Order.DESCENDING,
    revoked=False
)

response = client.get_transaction_history(
    any_transaction_id="123456789",
    revision=None,
    transaction_history_request=request,
    version=GetTransactionHistoryVersion.V2
)

for signed_transaction in response.signedTransactions:
    print(signed_transaction)

if response.hasMore:
    # Get next page
    next_response = client.get_transaction_history(
        any_transaction_id="123456789",
        revision=response.revision,
        transaction_history_request=request,
        version=GetTransactionHistoryVersion.V2
    )
```

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

### get_transaction_info

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Gets information for a specific transaction.

```APIDOC
## get_transaction_info

### Description
Gets information for a specific transaction.

### Method Signature
```python
def get_transaction_info(self, transaction_id: str) -> TransactionInfoResponse
```

### Parameters
#### Path Parameters
- **transaction_id** (str) - Required - A transaction identifier

### Response
#### Success Response
- **TransactionInfoResponse** — Response containing the signed transaction data

### Throws
- **APIException** — If the request could not be processed

### Example
```python
response = client.get_transaction_info(transaction_id="123456789")
print(response.signedTransactionInfo)
```
```

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

### Initialize AppStoreServerAPIClient

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

Initializes the App Store Server API Client with necessary credentials and environment configuration. Ensure the signing key is loaded correctly from a .p8 file.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment

# Load signing key from file
def read_signing_key(path: str) -> bytes:
    with open(path, 'rb') as f:
        return f.read()

# Initialize client
client = AppStoreServerAPIClient(
    signing_key=read_signing_key('/path/to/SubscriptionKey_ABCDEFGHIJ.p8'),
    key_id="ABCDEFGHIJ",
    issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",
    bundle_id="com.example.app",
    environment=Environment.PRODUCTION
)
```

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

### Retention Messaging - get_message_list

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets the list of uploaded messages.

```APIDOC
## get_message_list

### Description
Gets the list of uploaded messages.

### Method
GET

### Endpoint
/v1/retention/messages

### Response
#### Success Response (200)
- **GetMessageListResponse** (object) - The response object containing the list of messages.
```

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

### Retention Messaging - get_image_list

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets the list of uploaded images.

```APIDOC
## get_image_list

### Description
Gets the list of uploaded images.

### Method
GET

### Endpoint
/v1/retention/messages/images

### Response
#### Success Response (200)
- **GetImageListResponse** (object) - The response object containing the list of images.
```

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

### Initialize SignedDataVerifier

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/SignedDataVerifier.md

Demonstrates how to initialize the SignedDataVerifier with root certificates, enable online checks, specify the environment, and provide bundle ID and app Apple ID. Ensure root certificates are kept up-to-date.

```python
from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier, VerificationException
from appstoreserverlibrary.models.Environment import Environment
import json

def setup_verifier():
    # Load certificates
    root_certs = []
    with open('/path/to/AppleRootCA-G3.cer', 'rb') as f:
        root_certs.append(f.read())
    
    return SignedDataVerifier(
        root_certificates=root_certs,
        enable_online_checks=True,
        environment=Environment.PRODUCTION,
        bundle_id="com.example.app",
        app_apple_id=123456789
    )
```

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

### Real-time Events - get_realtime_url

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets the configured real-time event URL.

```APIDOC
## get_realtime_url

### Description
Gets the configured real-time event URL.

### Method
GET

### Endpoint
/v1/events/realtime-config

### Response
#### Success Response (200)
- **RealtimeUrlResponse** (object) - The response object containing the real-time event URL.
```

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

### Configure SignedDataVerifier for Production and Development

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

Demonstrates initializing the SignedDataVerifier for both production (with online checks) and development (without online checks for speed). Production requires online checks for security, while development can disable them.

```python
# Production: Enable online checks
prod_verifier = SignedDataVerifier(
    root_certificates=root_certs,
    enable_online_checks=True,  # Check revocation status
    environment=Environment.PRODUCTION,
    bundle_id="com.example.app",
    app_apple_id=123456789
)

# Development: Disable for speed
dev_verifier = SignedDataVerifier(
    root_certificates=root_certs,
    enable_online_checks=False,  # Skip revocation checks
    environment=Environment.SANDBOX,
    bundle_id="com.example.app"
)
```

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

### Get Image List

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Retrieves a list of all uploaded images, including their metadata.

```APIDOC
## get_image_list

### Description
Gets the list of uploaded images.

### Method
GET (assumed, based on retrieval action)

### Endpoint
/retention/messages/images (assumed, based on context)

### Parameters
None

### Request Example
```python
response = client.get_image_list()
for image in response.imageIds:
    print(f"Image: {image}")
```

### Response
#### Success Response (200)
- **imageIds** (list) - Response containing metadata for all uploaded images

#### Response Example
```json
{
  "imageIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "661f9511-f30c-420a-8e1d-111111111111"
  ]
}
```
```

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

### Initialize PromotionalOfferSignatureCreator

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/PromotionalOfferSignatureCreator.md

Instantiate the signature creator with your signing key, key ID, and app's bundle ID. Ensure the signing key is PEM-encoded ECDSA private key.

```python
from appstoreserverlibrary.promotional_offer import PromotionalOfferSignatureCreator

# Read key from file
with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
    signing_key = f.read()

signature_creator = PromotionalOfferSignatureCreator(
    signing_key=signing_key,
    key_id="ABCDEFGHIJ",
    bundle_id="com.example.app"
)
```

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

### get_refund_history

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Gets a paginated list of a customer's refunded in-app purchases.

```APIDOC
## get_refund_history

### Description
Gets a paginated list of a customer's refunded in-app purchases.

### Method Signature
```python
def get_refund_history(self, any_transaction_id: str, revision: Optional[str]) -> RefundHistoryResponse
```

### Parameters
#### Path Parameters
- **any_transaction_id** (str) - Required - Any transactionId, originalTransactionId, or appTransactionId
- **revision** (str) - Optional - Token for pagination; omit for the first call

### Response
#### Success Response
- **RefundHistoryResponse** — Response containing refund history and pagination token

### Throws
- **APIException** — If the request could not be processed

### Example
```python
response = client.get_refund_history(any_transaction_id="123456789", revision=None)
for signed_transaction in response.signedTransactions:
    print(signed_transaction)
```
```

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

### AppStoreServerAPIClient Constructor

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Initializes the App Store Server API Client with necessary credentials and configuration.

```APIDOC
## AppStoreServerAPIClient Constructor

### Description
Initializes the App Store Server API Client with necessary credentials and configuration.

### Parameters
#### Path Parameters
- **signing_key** (bytes) - Required - The signing key obtained from App Store Connect (PEM-encoded private key)
- **key_id** (str) - Required - The key identifier from App Store Connect
- **issuer_id** (str) - Required - The issuer identifier (team ID) from App Store Connect
- **bundle_id** (str) - Required - The bundle identifier of your app
- **environment** (Environment) - Required - The server environment (PRODUCTION or SANDBOX)

### Raises
- `ValueError`: If environment is XCODE or invalid

### Example
```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment

# Read key from file
with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
    signing_key = f.read()

client = AppStoreServerAPIClient(
    signing_key=signing_key,
    key_id="ABCDEFGHIJ",
    issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",
    bundle_id="com.example.app",
    environment=Environment.SANDBOX
)
```
```

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

### Get Message List

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Retrieves a list of all uploaded retention messages, including their metadata.

```APIDOC
## get_message_list

### Description
Gets the list of uploaded messages.

### Method
GET (assumed, based on retrieval action)

### Endpoint
/retention/messages (assumed, based on context)

### Parameters
None

### Request Example
```python
response = client.get_message_list()
for message_id in response.messages:
    print(f"Message: {message_id}")
```

### Response
#### Success Response (200)
- **messages** (list) - Response containing metadata for all uploaded messages

#### Response Example
```json
{
  "messages": [
    "550e8400-e29b-41d4-a716-446655440000",
    "661f9511-f30c-420a-8e1d-111111111111"
  ]
}
```
```

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

### Initialize App Store Server API Client

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/README.md

Initialize the API client with your credentials. Ensure your signing key, key ID, issuer ID, bundle ID, and environment are correctly configured. Refer to configuration.md for obtaining credentials.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment

# Read signing key from file
with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
    signing_key = f.read()

client = AppStoreServerAPIClient(
    signing_key=signing_key,
    key_id="ABCDEFGHIJ",
    issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",
    bundle_id="com.example.app",
    environment=Environment.PRODUCTION
)
```

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

### get_notification_history

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets a paginated list of notification history. Refer to AppStoreServerAPIClient.get_notification_history for parameter details.

```APIDOC
## get_notification_history

### Description
Gets a paginated list of notification history.

### Method Signature
```python
async def get_notification_history(self, pagination_token: Optional[str], notification_history_request: NotificationHistoryRequest) -> NotificationHistoryResponse
```

### Parameters
See `AppStoreServerAPIClient.get_notification_history` for parameter details.

### Returns
`NotificationHistoryResponse`
```

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

### Configure App Store Server API Client in Python

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/README.md

Instantiate the AppStoreServerAPIClient with the appropriate environment, either SANDBOX for testing or PRODUCTION for live transactions.

```python
from appstoreserverlibrary.models.Environment import Environment

# Sandbox for testing
client = AppStoreServerAPIClient(..., environment=Environment.SANDBOX)

# Production for live transactions  
client = AppStoreServerAPIClient(..., environment=Environment.PRODUCTION)
```

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

### get_app_transaction_info

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Gets app transaction information for the specified transaction ID. This method returns an AppTransactionInfoResponse.

```APIDOC
## get_app_transaction_info

### Description
Gets app transaction information for the specified transaction.

### Method
GET (Assumed based on typical SDK patterns for retrieval actions)

### Endpoint
/v1/transactions/{any_transaction_id} (Assumed based on typical SDK patterns)

### Parameters
#### Path Parameters
- **any_transaction_id** (string) - Required - Any transactionId, originalTransactionId, or appTransactionId

### Request Example
```python
response = client.get_app_transaction_info(any_transaction_id="123456789")
print(response.signedAppTransaction)
```

### Response
#### Success Response (200)
- **signedAppTransaction** (string) - The signed app transaction

#### Response Example
```json
{
  "signedAppTransaction": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2Nzg4ODk5MTIifQ..."
}
```

### Throws
- `APIException` — If the request could not be processed
```

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

### Initialize App Store Server API Client

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/00-START-HERE.md

Initialize the API client with your credentials and app details. Ensure your signing key, key ID, issuer ID, bundle ID, and environment are correctly configured.

```python
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment

# Read signing key from file (get from App Store Connect)
with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
    signing_key = f.read()

client = AppStoreServerAPIClient(
    signing_key=signing_key,
    key_id="ABCDEFGHIJ",  # From App Store Connect
    issuer_id="99b16628-15e4-4668-972b-eeff55eeff55",  # From App Store Connect
    bundle_id="com.example.app",  # Your app's bundle ID
    environment=Environment.PRODUCTION
)
```

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

### PromotionalOfferSignatureCreator Configuration

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

Instantiate `PromotionalOfferSignatureCreator` with your signing key, key ID, and bundle ID. Reuse the same signing key as used for the API client.

```python
from appstoreserverlibrary.promotional_offer import PromotionalOfferSignatureCreator

signature_creator = PromotionalOfferSignatureCreator(
    signing_key=signing_key,  # Reuse same key from API client
    key_id="ABCDEFGHIJ",
    bundle_id="com.example.app"
)
```

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

### get_transaction_history

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AppStoreServerAPIClient.md

Gets a paginated list of a customer's in-app purchase transaction history for your app.

```APIDOC
## get_transaction_history

### Description
Gets a paginated list of a customer's in-app purchase transaction history for your app.

### Method Signature
```python
def get_transaction_history(self, any_transaction_id: str, revision: Optional[str], transaction_history_request: TransactionHistoryRequest, version: GetTransactionHistoryVersion = GetTransactionHistoryVersion.V1) -> HistoryResponse
```

### Parameters
#### Path Parameters
- **any_transaction_id** (str) - Required - Any transactionId, originalTransactionId, or appTransactionId belonging to the customer
- **revision** (str) - Optional - Token for pagination; omit for the first call

#### Request Body
- **transaction_history_request** (TransactionHistoryRequest) - Required - Request with filter criteria
- **version** (GetTransactionHistoryVersion) - Optional - API version (V1 or V2); V2 recommended

### Response
#### Success Response
- **HistoryResponse** — Response containing transaction history and a revision token for pagination

### Throws
- **APIException** — If the request could not be processed

### Example
```python
from appstoreserverlibrary.models.TransactionHistoryRequest import TransactionHistoryRequest, ProductType, Order
from appstoreserverlibrary.api_client import GetTransactionHistoryVersion

request = TransactionHistoryRequest(
    productTypes=[ProductType.AUTO_RENEWABLE],
    sort=Order.DESCENDING,
    revoked=False
)

response = client.get_transaction_history(
    any_transaction_id="123456789",
    revision=None,
    transaction_history_request=request,
    version=GetTransactionHistoryVersion.V2
)

for signed_transaction in response.signedTransactions:
    print(signed_transaction)

if response.hasMore:
    # Get next page
    next_response = client.get_transaction_history(
        any_transaction_id="123456789",
        revision=response.revision,
        transaction_history_request=request,
        version=GetTransactionHistoryVersion.V2
    )
```
```

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

### PromotionalOfferSignatureCreator Constructor

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/PromotionalOfferSignatureCreator.md

Initializes the PromotionalOfferSignatureCreator with your signing key, key ID, and bundle ID.

```APIDOC
## Constructor

### Description
Initializes the `PromotionalOfferSignatureCreator` with the necessary credentials.

### Parameters
#### Path Parameters
- **signing_key** (bytes) - Required - The signing key obtained from App Store Connect (PEM-encoded ECDSA private key).
- **key_id** (str) - Required - The key identifier from App Store Connect.
- **bundle_id** (str) - Required - The bundle identifier of your app.

### Example
```python
from appstoreserverlibrary.promotional_offer import PromotionalOfferSignatureCreator

# Read key from file
with open('/path/to/SubscriptionKey_ABCDEFGHIJ.p8', 'rb') as f:
    signing_key = f.read()

signature_creator = PromotionalOfferSignatureCreator(
    signing_key=signing_key,
    key_id="ABCDEFGHIJ",
    bundle_id="com.example.app"
)
```
```

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

### App Transaction - get_app_transaction_info

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets app transaction information. Refer to AppStoreServerAPIClient.get_app_transaction_info for parameter details.

```APIDOC
## get_app_transaction_info

### Description
Gets app transaction information.

### Method
GET

### Endpoint
/v1/transactions/{any_transaction_id}

### Parameters
#### Path Parameters
- **any_transaction_id** (str) - Required - The transaction identifier.

### Response
#### Success Response (200)
- **AppTransactionInfoResponse** (object) - The response object containing app transaction information.
```

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

### Performance Testing - get_performance_test_results

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets performance test results. Refer to AppStoreServerAPIClient.get_performance_test_results for parameter details.

```APIDOC
## get_performance_test_results

### Description
Gets performance test results.

### Method
GET

### Endpoint
/v1/performance-testing/results/{request_id}

### Parameters
#### Path Parameters
- **request_id** (str) - Required - The identifier for the performance test request.

### Response
#### Success Response (200)
- **PerformanceTestResultResponse** (object) - The response object containing the performance test results.
```

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

### Load Configuration from Environment Variables

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

Load API client configuration, including signing keys and credentials, from environment variables. The environment can be specified, defaulting to 'SANDBOX'. Ensure the signing key file path is correctly set.

```python
import os
from appstoreserverlibrary.api_client import AppStoreServerAPIClient
from appstoreserverlibrary.models.Environment import Environment

# Load from environment
signing_key = open(os.environ['APPLE_SIGNING_KEY_PATH'], 'rb').read()

client = AppStoreServerAPIClient(
    signing_key=signing_key,
    key_id=os.environ['APPLE_KEY_ID'],
    issuer_id=os.environ['APPLE_ISSUER_ID'],
    bundle_id=os.environ['APPLE_BUNDLE_ID'],
    environment=Environment[os.environ.get('APPLE_ENVIRONMENT', 'SANDBOX')]
)
```

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

### Retention Messaging - get_default_message

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Gets the configured default message. Refer to AppStoreServerAPIClient.get_default_message for parameter details.

```APIDOC
## get_default_message

### Description
Gets the configured default message.

### Method
GET

### Endpoint
/v1/retention/default-messages/{product_id}/{locale}

### Parameters
#### Path Parameters
- **product_id** (str) - Required - The product identifier.
- **locale** (str) - Required - The locale of the default message.

### Response
#### Success Response (200)
- **DefaultConfigurationResponse** (object) - The response object containing the default message configuration.
```

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

### Initialize SignedDataVerifier

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/SignedDataVerifier.md

Instantiate the SignedDataVerifier with root certificates, environment details, and app information. Ensure root certificates are loaded in DER format and provide the app's Apple ID for the production environment.

```python
from appstoreserverlibrary.signed_data_verifier import SignedDataVerifier
from appstoreserverlibrary.models.Environment import Environment

# Load root certificates
root_certs = []
cert_files = [
    '/path/to/AppleRootCA-G3.cer',
    '/path/to/AppleRootCA-G2.cer',
    '/path/to/AppleRootCA-G1.cer'
]

for cert_file in cert_files:
    with open(cert_file, 'rb') as f:
        root_certs.append(f.read())

verifier = SignedDataVerifier(
    root_certificates=root_certs,
    enable_online_checks=True,
    environment=Environment.SANDBOX,
    bundle_id="com.example.app",
    app_apple_id=None  # Set to your app's Apple ID for production
)
```

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

### Configure Sandbox Environment API Client and Verifier

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/configuration.md

Set the environment to `Environment.SANDBOX` for testing purposes. The `app_apple_id` is not required for the verifier in the sandbox environment.

```python
from appstoreserverlibrary.models.Environment import Environment

# API Client
sandbox_client = AppStoreServerAPIClient(
    signing_key=signing_key,
    key_id=key_id,
    issuer_id=issuer_id,
    bundle_id="com.example.app",
    environment=Environment.SANDBOX  # For testing
)

# Verifier
sandbox_verifier = SignedDataVerifier(
    root_certificates=root_certs,
    enable_online_checks=True,
    environment=Environment.SANDBOX,
    bundle_id="com.example.app"
    # app_apple_id not required for SANDBOX
)
```

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

### Get All Subscription Statuses

Source: https://github.com/apple/app-store-server-library-python/blob/main/_autodocs/api-reference/AsyncAppStoreServerAPIClient.md

Retrieves the statuses for all of a customer's subscriptions using a transaction ID.

```python
async def get_all_subscription_statuses(self, any_transaction_id: str, 
                                       status: Optional[List[Status]] = None) -> StatusResponse
```