| Name | paritydeals-sdk JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | A Python SDK for interacting with the ParityDeals API to report usage and events. Supports synchronous and asynchronous operations using a unified client. |
| upload_time | 2025-07-23 12:32:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 ParityDeals
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
sdk
api
paritydeals
reporting
events
usage
async
sync
httpx
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
---
title: "Python SDK"
description: "Documentation for the ParityDeals Python SDK"
icon: 'python'
---
## Overview
The ParityDeals Python SDK provides a convenient way to interact with the ParityDeals REST APIs from your Python application. The SDK supports both synchronous and asynchronous operations.
## Installation
To install the ParityDeals SDK in your environment, run the following command:
```shell
pip install paritydeals-sdk
```
## Prerequisites
Before you can initialize the client and use the SDK methods, you need a Server API Key.
You can obtain this key from the ParityDeals application:
1. Navigate to Settings.
2. Go to the [Developers](https://app.paritydeals.com/settings/developers) section.
3. Copy the Server API Key.
Once copied, add this key to your environment variables or directly in your code (though environment variables are recommended for security).
```python
# Example of setting it in your code (ensure you handle this securely)
ACCESS_TOKEN = "__YOUR_API_KEY__"
```
## Configuring the Client
The SDK supports both synchronous and asynchronous clients. The primary difference lies in how you create the client instance. Once created, both client types can invoke the same methods to communicate with the ParityDeals application.
#### How to Create a Synchronous Client
Use the synchronous client for traditional, blocking I/O operations.
```python
from paritydeals_sdk import ParityDeals
client = ParityDeals.create_sync_client(access_token=ACCESS_TOKEN)
```
#### How to Create an Asynchronous Client
Use the asynchronous client for non-blocking I/O operations, suitable for applications using `asyncio`.
```python
from paritydeals_sdk import ParityDeals
async_client = ParityDeals.create_async_client(access_token=ACCESS_TOKEN)
```
## Supported Functionalities
The SDK currently supports the following operations:
1. [Customers](/backend-integration/python-sdk#customers)
2. [Checkout](/backend-integration/python-sdk#checkout-client-checkout)
3. [Entitlements](/backend-integration/python-sdk#entitlements-client-entitlements)
4. [Reporting](/backend-integration/python-sdk#reporting-client-reporting)
5. [Subscriptions](/backend-integration/python-sdk#subscriptions)
Further details on each method, including parameters and return values, should be added under each functionality.
---
## Customers
The `customers` module allows you to manage customer records within ParityDeals. You can access these operations via the `customers` attribute on an initialized `ParityDeals` client instance.
All methods are available in both synchronous and asynchronous versions, depending on how the `ParityDeals` client was instantiated.
---
### Creates a new customer
**Synchronous**:
```python
new_customer = client.customers.create(
customerId="unique-customer-id-123",
email="new.customer@example.com",
name="John Doe",
metadata={"source": "sdk_import", "priority": "high"}
)
print(f"Customer Created: ID = {new_customer.id}, Customer Client ID = {new_customer.customerId}")
```
**Asynchronous**:
```python
new_customer = await async_client.customers.create(
customerId="unique-customer-id-456",
email="another.new.customer@example.com",
name="Jane Roe"
)
print(f"Customer Created (Async): ID = {new_customer.id}, Customer Client ID = {new_customer.customerId}")
```
<Accordion title="Response">
```json
{
"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", // Server-generated UUID
"customerId": "unique-customer-id-123",
"name": "John Doe",
"email": "new.customer@example.com",
"details": {}, // Or any server-added details
"metadata": {
"source": "sdk_import",
"priority": "high"
},
"createdOn": "2025-06-04T06:03:30.195790Z",
"modifiedOn": "2025-06-04T06:03:30.195831Z"
}
```
</Accordion>
**Required Parameters:**
* `customerId` (str): A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.
**Optional Parameters:**
* `email` (str): The email address of the customer. Must be a valid email format.
* `name` (str): The name of the customer.
* `metadata` (Dict[str, str]): A dictionary of custom key-value pairs to store additional information about the customer.
**Returns:**
An instance of `CustomerResponse` (Pydantic model), representing the newly created customer record. Key attributes include:
* `id` (str): The server-generated unique UUID for the customer record.
* `customerId` (str): The client-provided customer identifier.
* `name` (str): The customer's name.
* `email` (str): The customer's email.
* `details` ([Dict[str, Any]]): Any server-added details about the customer (typically read-only).
* `metadata` ([Dict[str, str]]): The metadata associated with the customer.
* `createdOn` (string) : ISO 8601 timestamp of when the customer was created.
* `modifiedOn` (string) : ISO 8601 timestamp of when the customer was last modified.
### Updates an existing customer
This operation performs a partial update (PATCH), so you only need to provide the fields you want to change.
**Synchronous**:
```python
updated_customer = client.customers.update(
customerId="unique-customer-id-123",
name="Johnathan Doe",
metadata={"source": "sdk_import", "priority": "very_high", "status": "active"}
)
print(f"Customer Updated: {updated_customer.name}")
```
**Asynchronous**:
```python
updated_customer = await async_client.customers.update(
customerId="unique-customer-id-456",
email="jane.roe.updated@example.com"
)
print(f"Customer Updated (Async): {updated_customer.email}")
```
<Accordion title="Response">
```json
{
"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", // Server-generated UUID
"customerId": "unique-customer-id-123",
"name": "Johnathan Doe",
"email": "new.customer@example.com",
"details": {}, // Or any server-added details
"metadata": {
"source": "sdk_import",
"priority": "high",
"status": "active"
},
"createdOn": "2025-06-04T06:03:30.195790Z",
"modifiedOn": "2025-06-04T06:03:30.195831Z"
}
```
</Accordion>
**Parameters:**
**Required Parameters:**
* `customerId` (str): A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.
**Optional Parameters:**
* `email` (str): The email address of the customer. Must be a valid email format.
* `name` (str): The name of the customer.
* `metadata` (Dict[str, str]): A dictionary of custom key-value pairs to store additional information about the customer.
**Returns:**
An instance of `CustomerResponse` (Pydantic model), representing the newly created customer record. Key attributes include:
* `id` (str): The server-generated unique UUID for the customer record.
* `customerId` (str): The client-provided customer identifier.
* `name` (str): The customer's name.
* `email` (str): The customer's email.
* `details` ([Dict[str, Any]]): Any server-added details about the customer (typically read-only).
* `metadata` ([Dict[str, Any]]): The metadata associated with the customer.
* `createdOn` (string) : ISO 8601 timestamp of when the customer was created.
* `modifiedOn` (string) : ISO 8601 timestamp of when the customer was last modified.
---
## Checkout
The checkout module provides functionalities for creating and managing checkout sessions. You can access these operations via the checkout attribute on an initialized ParityDeals client instance.
`create_session(...)`
This operation creates a new checkout session for a customer, allowing them to proceed with a purchase or subscription.
**Synchronous**:
```python
response = client.checkout.create_session(
planIdentifier="plan-pro-monthly",
chargePeriod="MONTHLY",
customerId="cust_789", // Recommended, otherwise it will create a new customer
successUrl="https://paritydeals.com/checkout/success"
)
print(f"Checkout Session URL: {response.checkoutUrl}")
```
**Asynchronous**:
```python
response = await async_client.checkout.create_session(
planIdentifier="plan-pro-monthly",
chargePeriod="MONTHLY",
customerId="cust_789",
successUrl="https://paritydeals.com/checkout/success",
offeringId="96d3a293-34ac-48a5-b73d-976b15781afd",
pricingTableId="6db2717a-4e43-4ae1-a293-6c0a775f6264",
ruleId="f2ebc23f-3f79-4cf4-b17e-fe8e30a42ab2",
features=[{'identifier':"seats", 'quantity': 5}],
ipAddress="103.154.35.20",
)
print(f"Checkout Session URL: {response.checkoutUrl}")
```
<Accordion title="Response">
```json
{
"checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_b1sNi7D6u9iMCUFV1UZi9ZaiXKdOOmr3DCUW6XdCZIr5Id1F7#fid2cGd2ZndsdXsdjahsdkhsdhc%2FY2RpdmApJ3Zxd2x1YERmZmpwa3EnPydkZmZxWjRLZjV3X0BAckFBYGJKSEInKSdkdWxOYHwnPyd1blpxYHZxWjA0Tj1DSGdWRmwxYkdiMFxGQ29zf2BdTldOTGQzUlNqfWd9U1ZkanNHMlVnczxidEg0fFFqYVJNYzw8XEh2YVA8dkQ1bmA9NW5sS1c2PHE8hH89Q11Uf1E2NTVgY0M1Q0ZmYycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwc",
"checkoutSessionId": "cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G",
}
```
</Accordion>
**Required Parameters:**
* `planIdentifier` (str): The identifier of the specific plan the customer is checking out with. planIdentifier is mandatory.
* `successUrl` (str): The URL to which the user will be redirected after a successful checkout.
* `chargePeriod` (str): Required. The billing cycle for the subscription. Must be one of:
* `"ONE_TIME"`
* `"MONTHLY"`
* `"YEARLY"`
* `"WEEKLY"`
* `"DAILY"`
* `"THREE_MONTHS"`
* `"SIX_MONTHS"`
**Optional Parameters:**
* `offeringId` (str): The ID (uuid) of the offering the customer is checking out with.
* `pricingTableId` (str): Required. The id (uuid) of the pricingTable being used for this checkout. (Considered only if `offeringId` is not provided)
* `ruleId` (str): Required. The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided)
* `customerId` (str): Required. The ID of the customer initiating the checkout. (If not provided, a new customer will be created)
* `features` (List[Dict[str, Union[str, int]]]): **Required**. A list of dictionaries, where each dictionary represents a feature and its desired quantity. Each dictionary **must** have two keys:
* `"identifier"` (str): The unique identifier for the feature.
* `"quantity"` (int): The desired quantity for this feature.
* Example: `[{"identifier": "seats", "quantity": 10}, {"identifier": "api-calls-tier1", "quantity": 5000}]`
* `ipAddress` (str): The IP Address of the customer, used for location based pricing.
**Returns**:
An instance of CreateCheckoutSessionResponse (Pydantic model), which includes:
* `checkoutSessionId` (str): The unique ID for the created checkout session.
* `checkoutUrl` (str): The URL that the customer should be redirected to in order to complete the payment and activate the subscription/purchase.
---
## Entitlements
The entitlements module allows you to check and retrieve customer entitlements for various features. These operations target a specific edge API endpoint (https://edge.api.paritydeals.com by default) and use the GET HTTP method with query parameters.
### Checks if a specific customer has access to a particular feature.
This method directly returns a boolean indicating access status.
**Synchronous**:
```python
has_feature_access = client.entitlements.has_access(
customerId="cust_123",
featureId="premium-reporting"
)
```
**Asynchronous**:
```python
has_feature_access = await async_client.entitlements.has_access(
customerId="cust_456",
featureId="advanced-analytics"
)
```
<Accordion title="Response">
```shell
True
```
</Accordion>
**Required Parameters**:
* `customerId` (str): The unique identifier for the customer.
* `featureId` (str): The unique identifier for the feature whose access is being checked.
**Returns**:
* `bool`: True if the customer has access to the specified feature (considering feature type, limits, etc.), False otherwise or if the feature is not found in their entitlements.
### Retrieves the detailed entitlement information for a specific feature for a given customer.
**Synchronous**:
```python
entitlement_response = client.entitlements.get_entitlement(
customerId="cust_123",
featureId="premium-reporting"
)
```
**Asynchronous**:
```python
entitlement_response = await async_client.entitlements.get_entitlement(
customerId="cust_456",
featureId="advanced-analytics"
)
```
<Accordion title="Response">
```json
{
"customerId": "cust_456",
"entitlements": [
{
"featureId": "advanced-analytics",
"featureType": "METER",
"hasAccess": true,
"resetAt": "2025-05-22 08:27:45",
"hardLimit": false,
"usageLimit": 3,
"currentUsage": 0,
"remaining": 3
}
]
}
```
</Accordion>
**Required Parameters**:
* `customerId` (str): The unique identifier for the customer.
* `featureId` (str): The unique identifier for the feature whose access is being checked.
**Returns**:
An instance of CheckEntitlementsResponse (Pydantic model). When querying for a specific featureId, the entitlements list within this response is typically expected to contain a single EntitlementDetail object corresponding to the requested feature if found. The structure includes:
* `customerId` (str): The customer's ID.
* `entitlements` (List[EntitlementDetail]): A list containing the details for the requested feature. Each EntitlementDetail has fields like:
* `featureId`: str
* `hasAccess`: bool
* `featureType`: str
* `resetAt`: str
* `hardLimit`: Optional[bool]
* `usageLimit`: Optional[int]
* `currentUsage`: Optional[int]
* `remaining`: Optional[int]
### Retrieves all entitlements for a given customer.
**Synchronous**:
```python
all_entitlements_response = client.entitlements.get_all_entitlements(
customerId="cust_123"
)
```
**Asynchronous**:
```python
all_entitlements_response = await async_client.entitlements.get_all_entitlements(
customerId="cust_456"
)
```
<Accordion title="Response">
```json
{
"customerId": "cust_456",
"entitlements": [
{
"featureId": "advanced-analytics",
"featureType": "METER",
"hasAccess": true,
"resetAt": "2025-05-22 08:27:45",
"hardLimit": false,
"usageLimit": 3,
"currentUsage": 0,
"remaining": 3
}
]
}
```
</Accordion>
**Required Parameters**:
* `customerId` (str): The unique identifier for the customer.
**Returns**:
* `customerId` (str): The customer's ID.
* `entitlements` (List[EntitlementDetail]): A list containing the details for the requested feature. Each EntitlementDetail has fields like:
* `featureId`: str
* `hasAccess`: bool
* `featureType`: str
* `resetAt`: str
* `hardLimit`: Optional[bool]
* `usageLimit`: Optional[int]
* `currentUsage`: Optional[int]
* `remaining`: Optional[int]
---
## Reporting
### Reporting pre-aggregated usages for customer
This endpoint is used for reporting the pre-aggregated feature usage from your application (client-level) to the ParityDeals application. It allows you to update the usage count for a specific feature associated with a customer.
**Synchronous**:
```python
# Assuming 'client' is your synchronous ParityDeals client
response = client.reporting.report_usage(
value=150,
customerId="customer_001",
featureId="seats",
behaviour="SET" # Or 'DELTA'
)
```
**Asynchronous**:
```python
# Assuming 'async_client' is your asynchronous ParityDeals client
response = await async_client.reporting.report_usage(
value=75,
customerId="customer_001",
featureId="seats",
behaviour="DELTA"
)
```
<Accordion title="Response">
```json
{
"value": 150,
"customerId": "customer_001",
"featureId": "seats",
"behaviour": "SET",
"orgId": "1",
"eventName": "aggregated.usage",
"idempotencyKey": "597ee95063c744ed9bcc9b1cf5676a8a",
"timestamp": "2025-05-22 08:27:45.430732"
}
```
</Accordion>
**Required Parameters**:
* `value` (int): The usage value being reported.
* `customerId` (str): The unique identifier for the customer associated with this usage.
* `featureId` (str): The unique identifier for the feature for which usage is being reported.
* `behaviour` parameter dictates how the usage is updated:
* `SET`: This will replace the current usage value for the feature with the new `value` provided.
* `DELTA`: This will increment the existing usage value for the feature by the amount specified in the `value` parameter
**Returns**:
An instance of ReportUsageResponse (Pydantic model), which includes:
* `value` (int): The usage value that was recorded.
* `customerId` (str): The customer ID associated with the usage.
* `featureId` (str): The feature Identifier for which usage was recorded.
* `behaviour` (str): The behaviour type ("SET" or "DELTA") that was processed.
* `orgId` (str): The organization ID associated with this record, as determined by the server.
* `eventName` (str): An internal event name generated by the server for this usage report (e.g., "aggregated.usage").
* `idempotencyKey` (str): A unique idempotency key generated by the server for this specific usage report instance.
* `timestamp` (str): The server-generated UTC timestamp (str format) indicating when the usage report was processed.
### Reporting raw events for customer
Raw events are primarily used for metered billing scenarios, particularly when a customer is subscribed to a plan with usage-based billing (often referred to as "pay as you go"). Each event reported can contribute to the billable usage for that customer.
**Synchronous**:
```python
import uuid
# Assuming 'client' is your synchronous ParityDeals client
response = client.reporting.report_event(
customerId="customer_002",
eventName="api_invoked",
idempotencyKey=uuid.uuid4().hex,
timestamp="2025-05-22 07:53:55.747959",
properties={"featureId": "api-usage", "value": 2}
)
```
**Asynchronous**:
```python
import uuid
# Assuming 'async_client' is your asynchronous ParityDeals client
response = await async_client.reporting.report_event(
customerId="customer_002",
eventName="api_invoked",
idempotencyKey=uuid.uuid4().hex,
timestamp="2025-05-22 07:53:55.747959",
properties={"featureId": "api-usage", "value": 2}
)
```
<Accordion title="Response">
```json
{
"customerId": "customer_002",
"eventName": "api_invoked",
"idempotencyKey": "45f05c737a0b44d482c6042816d5645d",
"timestamp": "2025-05-22 07:53:55.747959",
"properties": {
"featureId": "api-usage",
"value": 2
},
"orgId": "1"
}
```
</Accordion>
**Required Parameters**:
* `customerId` (str): The unique identifier for the customer who performed the event.
* `eventName` (str): The name of the event (e.g., "user_login", "item_purchased", "feature_activated").
* `idempotencyKey` (str): A unique client-generated key to ensure that the event is processed at most once, even if the request is retried. A UUID is a good choice.
* `timestamp` (str): The UTC timestamp indicating when the event occurred. This must be a str formatted as "%Y-%m-%d %H:%M:%S.%f" (e.g., "2025-05-23 10:30:00.123456").
* `properties` ([Dict[str, Any]], default: None): A dictionary of additional custom properties associated with the event. Values can be strs, numbers, booleans.
**Returns**:
An instance of ReportEventResponse (Pydantic model), which includes:
* `customerId` (str): The customer ID associated with the event.
* `eventName` (str): The name of the event that was recorded.
* `idempotencyKey` (str): The idempotency key that was used for the request.
* `timestamp` (str): The timestamp (str format) that was recorded for the event.
* `properties` ([Dict[str, Any]]): The custom properties associated with the event, if provided and returned by the server.
* `orgId` (str): The organization ID associated with this record, as determined by the server.
---
## Subscriptions
The subscriptions module allows you to manage customer subscriptions, including updates and cancellation. You can access these operations via the `subscriptions` attribute on an initialized ParityDeals client instance.
### Updates an existing subscription to a new plan
**Synchronous**:
```python
# Assuming 'client' is your synchronous ParityDeals client
try:
response = client.subscriptions.update(
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
planIdentifier="premium-plan",
chargePeriod="MONTHLY",
)
print(response.subscriptionId)
except Exception as e:
print(f"Error updating subscription: {e}")
```
**Asynchronous**:
```python
# Assuming 'async_client' is your asynchronous ParityDeals client
try:
response = await async_client.subscriptions.update(
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
planIdentifier="new_plan_enterprise",
chargePeriod="YEARLY",
offeringId="offer_abc",
pricingTableId="pw_def",
ruleId="rule_ghi",
ipAddress="103.154.35.20",
features=[{'identifier': "seats", 'quantity': 10}]
)
print(response.subscriptionId)
except Exception as e:
print(f"Error updating subscription: {e}")
```
<Accordion title="Response">
```json
{
"subscriptionId": "dffaf07e-4517-47db-ba3a-59a05aa2d465"
}
```
</Accordion>
**Required Parameters**:
* `subscriptionId` (str): Required. The unique identifier of the subscription to be updated.
* `planIdentifier` (str): Required. The identifier of the new plan.
* `chargePeriod` (str): Required. The new charging period for the subscription. Must be one of:
* `"ONE_TIME"`
* `"MONTHLY"`
* `"YEARLY"`
* `"WEEKLY"`
* `"DAILY"`
* `"THREE_MONTHS"`
* `"SIX_MONTHS"`
**Optional Parameters:**
* `offeringId` (str): Optional. The ID of the new offering, if applicable.
* `pricingTableId` (str): Optional. The ID of the new pricingTable, if applicable.
* `ruleId` (str): Optional. The ID of the new pricing rule, if applicable.
* `ipAddress` (str): The IP Address of the customer, used for location based pricing.
* `features` ([List[Dict[str, Any]]]): Optional. A list of dictionaries, where each dictionary represents a feature and its desired quantity to update for the subscription. Each dictionary **must** have two keys:
* `"identifier"` (str): The unique identifier for the feature.
* `"quantity"` (int): The desired quantity for this feature.
* Example: `[{'identifier': 'seats', 'quantity': 10}, {'identifier': 'projects', 'quantity': 5}]`
**Returns**:
An instance of `UpdateSubscriptionResponse`, which includes:
* `subscriptionId` (str): UUID of the updated subscription.
### Cancel an active subscription for a customer.
**Synchronous**:
```python
# Assuming 'client' is your synchronous ParityDeals client
try:
response = client.subscriptions.cancel(
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
cancellationType="CURRENT_PERIOD_ENDS" # Or "IMMEDIATE", "SPECIFIC_DATE"
# cancellationDate="2025-12-31" # Required if cancellationType is "SPECIFIC_DATE"
)
print(response.message)
except Exception as e:
print(f"Error cancelling subscription: {e}")
```
**Asynchronous**:
```python
# Assuming 'async_client' is your asynchronous ParityDeals client
try:
response = await async_client.subscriptions.cancel(
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
cancellationType="IMMEDIATE"
)
print(response.message)
except Exception as e:
print(f"Error cancelling subscription: {e}")
```
<Accordion title="Response">
```json
{
"message": "Subscription cancellation processed successfully."
}
```
</Accordion>
**Required Parameters**:
* `subscriptionId` (str): The unique identifier of the subscription to be cancelled.
* `cancellationType` (str): The type of cancellation to perform. Must be one of:
* `"IMMEDIATE"`: The subscription is cancelled immediately.
* `"CURRENT_PERIOD_ENDS"`: The subscription will remain active until the end of the current billing period and then cancel.
* `"SPECIFIC_DATE"`: The subscription will be cancelled on the specified `cancellationDate`.
* `cancellationDate` (str): The specific date for cancellation if `cancellationType` is `"SPECIFIC_DATE"`. Must be in `YYYY-MM-DD` format. This parameter is **required** if `cancellationType` is `"SPECIFIC_DATE"`.
**Returns**:
An instance of `CancelSubscriptionResponse`, which includes:
* `message` (str): A confirmation message indicating the result of the cancellation request.
Raw data
{
"_id": null,
"home_page": null,
"name": "paritydeals-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sdk, api, paritydeals, reporting, events, usage, async, sync, httpx",
"author": null,
"author_email": "Geo Jacob / ParityDeals <geo@paritydeals.com>",
"download_url": "https://files.pythonhosted.org/packages/b2/da/950fbc679f8f65b9a92b82dbb77c657bcc8f853f553a6c62f30c2d949c9a/paritydeals_sdk-1.0.1.tar.gz",
"platform": null,
"description": "---\ntitle: \"Python SDK\"\ndescription: \"Documentation for the ParityDeals Python SDK\"\nicon: 'python'\n---\n\n## Overview\n\nThe ParityDeals Python SDK provides a convenient way to interact with the ParityDeals REST APIs from your Python application. The SDK supports both synchronous and asynchronous operations.\n\n\n## Installation\n\nTo install the ParityDeals SDK in your environment, run the following command:\n\n```shell\npip install paritydeals-sdk\n```\n\n## Prerequisites\n\nBefore you can initialize the client and use the SDK methods, you need a Server API Key.\n\nYou can obtain this key from the ParityDeals application:\n\n 1. Navigate to Settings.\n 2. Go to the [Developers](https://app.paritydeals.com/settings/developers) section.\n 3. Copy the Server API Key.\n\nOnce copied, add this key to your environment variables or directly in your code (though environment variables are recommended for security).\n\n\n```python\n# Example of setting it in your code (ensure you handle this securely)\nACCESS_TOKEN = \"__YOUR_API_KEY__\"\n```\n\n## Configuring the Client\n\nThe SDK supports both synchronous and asynchronous clients. The primary difference lies in how you create the client instance. Once created, both client types can invoke the same methods to communicate with the ParityDeals application.\n\n\n#### How to Create a Synchronous Client\n\nUse the synchronous client for traditional, blocking I/O operations.\n\n```python\nfrom paritydeals_sdk import ParityDeals\n\nclient = ParityDeals.create_sync_client(access_token=ACCESS_TOKEN)\n```\n\n#### How to Create an Asynchronous Client\nUse the asynchronous client for non-blocking I/O operations, suitable for applications using `asyncio`.\n\n\n```python\nfrom paritydeals_sdk import ParityDeals\n\nasync_client = ParityDeals.create_async_client(access_token=ACCESS_TOKEN)\n```\n\n\n\n## Supported Functionalities\n\nThe SDK currently supports the following operations:\n\n 1. [Customers](/backend-integration/python-sdk#customers)\n\n 2. [Checkout](/backend-integration/python-sdk#checkout-client-checkout)\n\n 3. [Entitlements](/backend-integration/python-sdk#entitlements-client-entitlements)\n\n 4. [Reporting](/backend-integration/python-sdk#reporting-client-reporting)\n\n 5. [Subscriptions](/backend-integration/python-sdk#subscriptions)\n\n\nFurther details on each method, including parameters and return values, should be added under each functionality.\n\n---\n\n## Customers\n\nThe `customers` module allows you to manage customer records within ParityDeals. You can access these operations via the `customers` attribute on an initialized `ParityDeals` client instance.\n\nAll methods are available in both synchronous and asynchronous versions, depending on how the `ParityDeals` client was instantiated.\n\n---\n\n### Creates a new customer\n\n\n**Synchronous**:\n\n ```python\n new_customer = client.customers.create(\n customerId=\"unique-customer-id-123\",\n email=\"new.customer@example.com\",\n name=\"John Doe\",\n metadata={\"source\": \"sdk_import\", \"priority\": \"high\"}\n )\n print(f\"Customer Created: ID = {new_customer.id}, Customer Client ID = {new_customer.customerId}\")\n ```\n\n**Asynchronous**:\n ```python\n new_customer = await async_client.customers.create(\n customerId=\"unique-customer-id-456\",\n email=\"another.new.customer@example.com\",\n name=\"Jane Roe\"\n )\n print(f\"Customer Created (Async): ID = {new_customer.id}, Customer Client ID = {new_customer.customerId}\")\n ```\n\n<Accordion title=\"Response\">\n```json\n{\n \"id\": \"a1b2c3d4-e5f6-7890-1234-567890abcdef\", // Server-generated UUID\n \"customerId\": \"unique-customer-id-123\",\n \"name\": \"John Doe\",\n \"email\": \"new.customer@example.com\",\n \"details\": {}, // Or any server-added details\n \"metadata\": {\n \"source\": \"sdk_import\",\n \"priority\": \"high\"\n },\n \"createdOn\": \"2025-06-04T06:03:30.195790Z\",\n \"modifiedOn\": \"2025-06-04T06:03:30.195831Z\"\n}\n```\n</Accordion>\n\n\n**Required Parameters:**\n\n* `customerId` (str): A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.\n\n**Optional Parameters:**\n\n* `email` (str): The email address of the customer. Must be a valid email format.\n* `name` (str): The name of the customer.\n* `metadata` (Dict[str, str]): A dictionary of custom key-value pairs to store additional information about the customer.\n\n\n**Returns:**\nAn instance of `CustomerResponse` (Pydantic model), representing the newly created customer record. Key attributes include:\n\n* `id` (str): The server-generated unique UUID for the customer record.\n* `customerId` (str): The client-provided customer identifier.\n* `name` (str): The customer's name.\n* `email` (str): The customer's email.\n* `details` ([Dict[str, Any]]): Any server-added details about the customer (typically read-only).\n* `metadata` ([Dict[str, str]]): The metadata associated with the customer.\n* `createdOn` (string) : ISO 8601 timestamp of when the customer was created.\n* `modifiedOn` (string) : ISO 8601 timestamp of when the customer was last modified.\n\n### Updates an existing customer\n\nThis operation performs a partial update (PATCH), so you only need to provide the fields you want to change.\n\n**Synchronous**:\n\n ```python\n updated_customer = client.customers.update(\n customerId=\"unique-customer-id-123\",\n name=\"Johnathan Doe\",\n metadata={\"source\": \"sdk_import\", \"priority\": \"very_high\", \"status\": \"active\"}\n )\n print(f\"Customer Updated: {updated_customer.name}\")\n ```\n\n**Asynchronous**:\n\n ```python\n updated_customer = await async_client.customers.update(\n customerId=\"unique-customer-id-456\",\n email=\"jane.roe.updated@example.com\"\n )\n print(f\"Customer Updated (Async): {updated_customer.email}\")\n ```\n\n<Accordion title=\"Response\">\n```json\n{\n \"id\": \"a1b2c3d4-e5f6-7890-1234-567890abcdef\", // Server-generated UUID\n \"customerId\": \"unique-customer-id-123\",\n \"name\": \"Johnathan Doe\",\n \"email\": \"new.customer@example.com\",\n \"details\": {}, // Or any server-added details\n \"metadata\": {\n \"source\": \"sdk_import\",\n \"priority\": \"high\",\n \"status\": \"active\"\n },\n \"createdOn\": \"2025-06-04T06:03:30.195790Z\",\n \"modifiedOn\": \"2025-06-04T06:03:30.195831Z\"\n}\n```\n</Accordion>\n\n\n**Parameters:**\n\n**Required Parameters:**\n\n* `customerId` (str): A unique identifier for the customer that you define. This ID will be used to reference the customer in subsequent API calls.\n\n**Optional Parameters:**\n\n* `email` (str): The email address of the customer. Must be a valid email format.\n* `name` (str): The name of the customer.\n* `metadata` (Dict[str, str]): A dictionary of custom key-value pairs to store additional information about the customer.\n\n\n**Returns:**\nAn instance of `CustomerResponse` (Pydantic model), representing the newly created customer record. Key attributes include:\n\n* `id` (str): The server-generated unique UUID for the customer record.\n* `customerId` (str): The client-provided customer identifier.\n* `name` (str): The customer's name.\n* `email` (str): The customer's email.\n* `details` ([Dict[str, Any]]): Any server-added details about the customer (typically read-only).\n* `metadata` ([Dict[str, Any]]): The metadata associated with the customer.\n* `createdOn` (string) : ISO 8601 timestamp of when the customer was created.\n* `modifiedOn` (string) : ISO 8601 timestamp of when the customer was last modified.\n\n---\n\n## Checkout\n\nThe checkout module provides functionalities for creating and managing checkout sessions. You can access these operations via the checkout attribute on an initialized ParityDeals client instance.\n\n`create_session(...)`\nThis operation creates a new checkout session for a customer, allowing them to proceed with a purchase or subscription.\n\n**Synchronous**:\n\n```python\nresponse = client.checkout.create_session(\n planIdentifier=\"plan-pro-monthly\",\n chargePeriod=\"MONTHLY\",\n customerId=\"cust_789\", // Recommended, otherwise it will create a new customer\n successUrl=\"https://paritydeals.com/checkout/success\"\n)\nprint(f\"Checkout Session URL: {response.checkoutUrl}\")\n```\n\n**Asynchronous**:\n\n```python\nresponse = await async_client.checkout.create_session(\n planIdentifier=\"plan-pro-monthly\",\n chargePeriod=\"MONTHLY\",\n customerId=\"cust_789\",\n successUrl=\"https://paritydeals.com/checkout/success\",\n offeringId=\"96d3a293-34ac-48a5-b73d-976b15781afd\",\n pricingTableId=\"6db2717a-4e43-4ae1-a293-6c0a775f6264\",\n ruleId=\"f2ebc23f-3f79-4cf4-b17e-fe8e30a42ab2\",\n features=[{'identifier':\"seats\", 'quantity': 5}],\n ipAddress=\"103.154.35.20\",\n)\nprint(f\"Checkout Session URL: {response.checkoutUrl}\")\n\n```\n\n\n<Accordion title=\"Response\">\n\n ```json\n {\n \"checkoutUrl\": \"https://checkout.stripe.com/c/pay/cs_test_b1sNi7D6u9iMCUFV1UZi9ZaiXKdOOmr3DCUW6XdCZIr5Id1F7#fid2cGd2ZndsdXsdjahsdkhsdhc%2FY2RpdmApJ3Zxd2x1YERmZmpwa3EnPydkZmZxWjRLZjV3X0BAckFBYGJKSEInKSdkdWxOYHwnPyd1blpxYHZxWjA0Tj1DSGdWRmwxYkdiMFxGQ29zf2BdTldOTGQzUlNqfWd9U1ZkanNHMlVnczxidEg0fFFqYVJNYzw8XEh2YVA8dkQ1bmA9NW5sS1c2PHE8hH89Q11Uf1E2NTVgY0M1Q0ZmYycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwc\",\n \"checkoutSessionId\": \"cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G\",\n }\n ```\n</Accordion>\n\n\n**Required Parameters:**\n\n* `planIdentifier` (str): The identifier of the specific plan the customer is checking out with. planIdentifier is mandatory.\n\n* `successUrl` (str): The URL to which the user will be redirected after a successful checkout.\n\n* `chargePeriod` (str): Required. The billing cycle for the subscription. Must be one of:\n\n * `\"ONE_TIME\"`\n\n * `\"MONTHLY\"`\n\n * `\"YEARLY\"`\n\n * `\"WEEKLY\"`\n\n * `\"DAILY\"`\n\n * `\"THREE_MONTHS\"`\n\n * `\"SIX_MONTHS\"`\n\n\n\n**Optional Parameters:**\n\n * `offeringId` (str): The ID (uuid) of the offering the customer is checking out with.\n\n * `pricingTableId` (str): Required. The id (uuid) of the pricingTable being used for this checkout. (Considered only if `offeringId` is not provided)\n\n * `ruleId` (str): Required. The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided)\n\n * `customerId` (str): Required. The ID of the customer initiating the checkout. (If not provided, a new customer will be created)\n\n * `features` (List[Dict[str, Union[str, int]]]): **Required**. A list of dictionaries, where each dictionary represents a feature and its desired quantity. Each dictionary **must** have two keys:\n * `\"identifier\"` (str): The unique identifier for the feature.\n * `\"quantity\"` (int): The desired quantity for this feature.\n * Example: `[{\"identifier\": \"seats\", \"quantity\": 10}, {\"identifier\": \"api-calls-tier1\", \"quantity\": 5000}]`\n\n * `ipAddress` (str): The IP Address of the customer, used for location based pricing.\n\n\n**Returns**:\n\nAn instance of CreateCheckoutSessionResponse (Pydantic model), which includes:\n\n * `checkoutSessionId` (str): The unique ID for the created checkout session.\n\n * `checkoutUrl` (str): The URL that the customer should be redirected to in order to complete the payment and activate the subscription/purchase.\n\n---\n\n## Entitlements\n\nThe entitlements module allows you to check and retrieve customer entitlements for various features. These operations target a specific edge API endpoint (https://edge.api.paritydeals.com by default) and use the GET HTTP method with query parameters.\n\n\n### Checks if a specific customer has access to a particular feature.\nThis method directly returns a boolean indicating access status.\n\n**Synchronous**:\n\n```python\nhas_feature_access = client.entitlements.has_access(\n customerId=\"cust_123\",\n featureId=\"premium-reporting\"\n)\n```\n\n**Asynchronous**:\n\n```python\nhas_feature_access = await async_client.entitlements.has_access(\n customerId=\"cust_456\",\n featureId=\"advanced-analytics\"\n)\n```\n\n<Accordion title=\"Response\">\n\n ```shell\n True\n ```\n</Accordion>\n\n**Required Parameters**:\n\n * `customerId` (str): The unique identifier for the customer.\n\n * `featureId` (str): The unique identifier for the feature whose access is being checked.\n\n**Returns**:\n\n * `bool`: True if the customer has access to the specified feature (considering feature type, limits, etc.), False otherwise or if the feature is not found in their entitlements.\n\n\n\n### Retrieves the detailed entitlement information for a specific feature for a given customer.\n\n**Synchronous**:\n\n```python\nentitlement_response = client.entitlements.get_entitlement(\n customerId=\"cust_123\",\n featureId=\"premium-reporting\"\n)\n```\n\n\n**Asynchronous**:\n\n```python\nentitlement_response = await async_client.entitlements.get_entitlement(\n customerId=\"cust_456\",\n featureId=\"advanced-analytics\"\n)\n```\n\n<Accordion title=\"Response\">\n\n ```json\n {\n \"customerId\": \"cust_456\",\n \"entitlements\": [\n {\n \"featureId\": \"advanced-analytics\",\n \"featureType\": \"METER\",\n \"hasAccess\": true,\n \"resetAt\": \"2025-05-22 08:27:45\",\n \"hardLimit\": false,\n \"usageLimit\": 3,\n \"currentUsage\": 0,\n \"remaining\": 3\n }\n ]\n }\n ```\n</Accordion>\n\n**Required Parameters**:\n\n * `customerId` (str): The unique identifier for the customer.\n\n * `featureId` (str): The unique identifier for the feature whose access is being checked.\n\n**Returns**:\n\nAn instance of CheckEntitlementsResponse (Pydantic model). When querying for a specific featureId, the entitlements list within this response is typically expected to contain a single EntitlementDetail object corresponding to the requested feature if found. The structure includes:\n\n * `customerId` (str): The customer's ID.\n\n * `entitlements` (List[EntitlementDetail]): A list containing the details for the requested feature. Each EntitlementDetail has fields like:\n\n * `featureId`: str\n\n * `hasAccess`: bool\n\n * `featureType`: str\n\n * `resetAt`: str\n\n * `hardLimit`: Optional[bool]\n\n * `usageLimit`: Optional[int]\n\n * `currentUsage`: Optional[int]\n\n * `remaining`: Optional[int]\n\n\n### Retrieves all entitlements for a given customer.\n\n**Synchronous**:\n\n```python\nall_entitlements_response = client.entitlements.get_all_entitlements(\n customerId=\"cust_123\"\n)\n```\n\n**Asynchronous**:\n\n```python\nall_entitlements_response = await async_client.entitlements.get_all_entitlements(\n customerId=\"cust_456\"\n)\n```\n\n<Accordion title=\"Response\">\n\n\n ```json\n {\n \"customerId\": \"cust_456\",\n \"entitlements\": [\n {\n \"featureId\": \"advanced-analytics\",\n \"featureType\": \"METER\",\n \"hasAccess\": true,\n \"resetAt\": \"2025-05-22 08:27:45\",\n \"hardLimit\": false,\n \"usageLimit\": 3,\n \"currentUsage\": 0,\n \"remaining\": 3\n }\n ]\n }\n ```\n</Accordion>\n\n**Required Parameters**:\n\n * `customerId` (str): The unique identifier for the customer.\n\n\n**Returns**:\n\n\n * `customerId` (str): The customer's ID.\n\n * `entitlements` (List[EntitlementDetail]): A list containing the details for the requested feature. Each EntitlementDetail has fields like:\n\n * `featureId`: str\n\n * `hasAccess`: bool\n\n * `featureType`: str\n\n * `resetAt`: str\n\n * `hardLimit`: Optional[bool]\n\n * `usageLimit`: Optional[int]\n\n * `currentUsage`: Optional[int]\n\n * `remaining`: Optional[int]\n\n---\n\n## Reporting\n\n### Reporting pre-aggregated usages for customer\n\nThis endpoint is used for reporting the pre-aggregated feature usage from your application (client-level) to the ParityDeals application. It allows you to update the usage count for a specific feature associated with a customer.\n\n\n**Synchronous**:\n\n```python\n# Assuming 'client' is your synchronous ParityDeals client\nresponse = client.reporting.report_usage(\n value=150,\n customerId=\"customer_001\",\n featureId=\"seats\",\n behaviour=\"SET\" # Or 'DELTA'\n)\n```\n\n**Asynchronous**:\n\n```python\n# Assuming 'async_client' is your asynchronous ParityDeals client\nresponse = await async_client.reporting.report_usage(\n value=75,\n customerId=\"customer_001\",\n featureId=\"seats\",\n behaviour=\"DELTA\"\n)\n```\n\n<Accordion title=\"Response\">\n\n\n ```json\n {\n \"value\": 150,\n \"customerId\": \"customer_001\",\n \"featureId\": \"seats\",\n \"behaviour\": \"SET\",\n \"orgId\": \"1\",\n \"eventName\": \"aggregated.usage\",\n \"idempotencyKey\": \"597ee95063c744ed9bcc9b1cf5676a8a\",\n \"timestamp\": \"2025-05-22 08:27:45.430732\"\n }\n ```\n</Accordion>\n\n\n**Required Parameters**:\n\n * `value` (int): The usage value being reported.\n\n * `customerId` (str): The unique identifier for the customer associated with this usage.\n\n * `featureId` (str): The unique identifier for the feature for which usage is being reported.\n\n * `behaviour` parameter dictates how the usage is updated:\n\n * `SET`: This will replace the current usage value for the feature with the new `value` provided.\n\n * `DELTA`: This will increment the existing usage value for the feature by the amount specified in the `value` parameter\n\n\n**Returns**:\n\nAn instance of ReportUsageResponse (Pydantic model), which includes:\n\n * `value` (int): The usage value that was recorded.\n\n * `customerId` (str): The customer ID associated with the usage.\n\n * `featureId` (str): The feature Identifier for which usage was recorded.\n\n * `behaviour` (str): The behaviour type (\"SET\" or \"DELTA\") that was processed.\n\n * `orgId` (str): The organization ID associated with this record, as determined by the server.\n\n * `eventName` (str): An internal event name generated by the server for this usage report (e.g., \"aggregated.usage\").\n\n * `idempotencyKey` (str): A unique idempotency key generated by the server for this specific usage report instance.\n\n * `timestamp` (str): The server-generated UTC timestamp (str format) indicating when the usage report was processed.\n\n\n### Reporting raw events for customer\n\nRaw events are primarily used for metered billing scenarios, particularly when a customer is subscribed to a plan with usage-based billing (often referred to as \"pay as you go\"). Each event reported can contribute to the billable usage for that customer.\n\n**Synchronous**:\n\n```python\nimport uuid\n\n# Assuming 'client' is your synchronous ParityDeals client\nresponse = client.reporting.report_event(\n customerId=\"customer_002\",\n eventName=\"api_invoked\",\n idempotencyKey=uuid.uuid4().hex,\n timestamp=\"2025-05-22 07:53:55.747959\",\n properties={\"featureId\": \"api-usage\", \"value\": 2}\n)\n\n```\n\n**Asynchronous**:\n\n```python\nimport uuid\n\n# Assuming 'async_client' is your asynchronous ParityDeals client\nresponse = await async_client.reporting.report_event(\n customerId=\"customer_002\",\n eventName=\"api_invoked\",\n idempotencyKey=uuid.uuid4().hex,\n timestamp=\"2025-05-22 07:53:55.747959\",\n properties={\"featureId\": \"api-usage\", \"value\": 2}\n)\n```\n\n<Accordion title=\"Response\">\n\n\n ```json\n {\n \"customerId\": \"customer_002\",\n \"eventName\": \"api_invoked\",\n \"idempotencyKey\": \"45f05c737a0b44d482c6042816d5645d\",\n \"timestamp\": \"2025-05-22 07:53:55.747959\",\n \"properties\": {\n \"featureId\": \"api-usage\",\n \"value\": 2\n },\n \"orgId\": \"1\"\n }\n ```\n</Accordion>\n\n\n**Required Parameters**:\n\n * `customerId` (str): The unique identifier for the customer who performed the event.\n\n * `eventName` (str): The name of the event (e.g., \"user_login\", \"item_purchased\", \"feature_activated\").\n\n * `idempotencyKey` (str): A unique client-generated key to ensure that the event is processed at most once, even if the request is retried. A UUID is a good choice.\n\n * `timestamp` (str): The UTC timestamp indicating when the event occurred. This must be a str formatted as \"%Y-%m-%d %H:%M:%S.%f\" (e.g., \"2025-05-23 10:30:00.123456\").\n\n * `properties` ([Dict[str, Any]], default: None): A dictionary of additional custom properties associated with the event. Values can be strs, numbers, booleans.\n\n**Returns**:\n\nAn instance of ReportEventResponse (Pydantic model), which includes:\n\n * `customerId` (str): The customer ID associated with the event.\n\n * `eventName` (str): The name of the event that was recorded.\n\n * `idempotencyKey` (str): The idempotency key that was used for the request.\n\n * `timestamp` (str): The timestamp (str format) that was recorded for the event.\n\n * `properties` ([Dict[str, Any]]): The custom properties associated with the event, if provided and returned by the server.\n\n * `orgId` (str): The organization ID associated with this record, as determined by the server.\n\n---\n\n## Subscriptions\n\nThe subscriptions module allows you to manage customer subscriptions, including updates and cancellation. You can access these operations via the `subscriptions` attribute on an initialized ParityDeals client instance.\n\n\n### Updates an existing subscription to a new plan\n\n\n**Synchronous**:\n\n```python\n# Assuming 'client' is your synchronous ParityDeals client\ntry:\n response = client.subscriptions.update(\n subscriptionId=\"78058918-9746-4280-9b9b-1bd5115eec6e\",\n planIdentifier=\"premium-plan\",\n chargePeriod=\"MONTHLY\",\n )\n print(response.subscriptionId)\nexcept Exception as e:\n print(f\"Error updating subscription: {e}\")\n```\n\n\n**Asynchronous**:\n\n```python\n# Assuming 'async_client' is your asynchronous ParityDeals client\ntry:\n response = await async_client.subscriptions.update(\n subscriptionId=\"78058918-9746-4280-9b9b-1bd5115eec6e\",\n planIdentifier=\"new_plan_enterprise\",\n chargePeriod=\"YEARLY\",\n offeringId=\"offer_abc\",\n pricingTableId=\"pw_def\",\n ruleId=\"rule_ghi\",\n ipAddress=\"103.154.35.20\",\n features=[{'identifier': \"seats\", 'quantity': 10}]\n )\n print(response.subscriptionId)\nexcept Exception as e:\n print(f\"Error updating subscription: {e}\")\n```\n\n<Accordion title=\"Response\">\n\n ```json\n {\n \"subscriptionId\": \"dffaf07e-4517-47db-ba3a-59a05aa2d465\"\n }\n ```\n</Accordion>\n\n**Required Parameters**:\n\n* `subscriptionId` (str): Required. The unique identifier of the subscription to be updated.\n* `planIdentifier` (str): Required. The identifier of the new plan.\n* `chargePeriod` (str): Required. The new charging period for the subscription. Must be one of:\n * `\"ONE_TIME\"`\n * `\"MONTHLY\"`\n * `\"YEARLY\"`\n * `\"WEEKLY\"`\n * `\"DAILY\"`\n * `\"THREE_MONTHS\"`\n * `\"SIX_MONTHS\"`\n\n**Optional Parameters:**\n\n* `offeringId` (str): Optional. The ID of the new offering, if applicable.\n* `pricingTableId` (str): Optional. The ID of the new pricingTable, if applicable.\n* `ruleId` (str): Optional. The ID of the new pricing rule, if applicable.\n* `ipAddress` (str): The IP Address of the customer, used for location based pricing.\n* `features` ([List[Dict[str, Any]]]): Optional. A list of dictionaries, where each dictionary represents a feature and its desired quantity to update for the subscription. Each dictionary **must** have two keys:\n * `\"identifier\"` (str): The unique identifier for the feature.\n * `\"quantity\"` (int): The desired quantity for this feature.\n * Example: `[{'identifier': 'seats', 'quantity': 10}, {'identifier': 'projects', 'quantity': 5}]`\n\n**Returns**:\n\nAn instance of `UpdateSubscriptionResponse`, which includes:\n\n* `subscriptionId` (str): UUID of the updated subscription.\n\n\n### Cancel an active subscription for a customer.\n\n\n**Synchronous**:\n\n```python\n# Assuming 'client' is your synchronous ParityDeals client\ntry:\n response = client.subscriptions.cancel(\n subscriptionId=\"78058918-9746-4280-9b9b-1bd5115eec6e\",\n cancellationType=\"CURRENT_PERIOD_ENDS\" # Or \"IMMEDIATE\", \"SPECIFIC_DATE\"\n # cancellationDate=\"2025-12-31\" # Required if cancellationType is \"SPECIFIC_DATE\"\n )\n print(response.message)\nexcept Exception as e:\n print(f\"Error cancelling subscription: {e}\")\n```\n\n\n**Asynchronous**:\n\n```python\n# Assuming 'async_client' is your asynchronous ParityDeals client\ntry:\n response = await async_client.subscriptions.cancel(\n subscriptionId=\"78058918-9746-4280-9b9b-1bd5115eec6e\",\n cancellationType=\"IMMEDIATE\"\n )\n print(response.message)\nexcept Exception as e:\n print(f\"Error cancelling subscription: {e}\")\n```\n\n<Accordion title=\"Response\">\n\n ```json\n {\n \"message\": \"Subscription cancellation processed successfully.\"\n }\n ```\n</Accordion>\n\n**Required Parameters**:\n\n* `subscriptionId` (str): The unique identifier of the subscription to be cancelled.\n\n* `cancellationType` (str): The type of cancellation to perform. Must be one of:\n\n * `\"IMMEDIATE\"`: The subscription is cancelled immediately.\n * `\"CURRENT_PERIOD_ENDS\"`: The subscription will remain active until the end of the current billing period and then cancel.\n * `\"SPECIFIC_DATE\"`: The subscription will be cancelled on the specified `cancellationDate`.\n\n* `cancellationDate` (str): The specific date for cancellation if `cancellationType` is `\"SPECIFIC_DATE\"`. Must be in `YYYY-MM-DD` format. This parameter is **required** if `cancellationType` is `\"SPECIFIC_DATE\"`.\n\n**Returns**:\n\nAn instance of `CancelSubscriptionResponse`, which includes:\n\n* `message` (str): A confirmation message indicating the result of the cancellation request.\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 ParityDeals\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A Python SDK for interacting with the ParityDeals API to report usage and events. Supports synchronous and asynchronous operations using a unified client.",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/paritydeals/paritydeals-python-sdk/issues",
"Homepage": "https://github.com/paritydeals/paritydeals-python-sdk"
},
"split_keywords": [
"sdk",
" api",
" paritydeals",
" reporting",
" events",
" usage",
" async",
" sync",
" httpx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "45fe7235a7a74c40593a110dd32a41b25bfaa3662dd1a5305609a217fd8cff5b",
"md5": "23a0c442fb05b38d78e21fdefcd20cad",
"sha256": "97703ecf1fb85dbccbd1adb9987b80ef407c0dab3422d6e5327ea24a5c3c53b3"
},
"downloads": -1,
"filename": "paritydeals_sdk-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23a0c442fb05b38d78e21fdefcd20cad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33794,
"upload_time": "2025-07-23T12:32:11",
"upload_time_iso_8601": "2025-07-23T12:32:11.463064Z",
"url": "https://files.pythonhosted.org/packages/45/fe/7235a7a74c40593a110dd32a41b25bfaa3662dd1a5305609a217fd8cff5b/paritydeals_sdk-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b2da950fbc679f8f65b9a92b82dbb77c657bcc8f853f553a6c62f30c2d949c9a",
"md5": "c1686925ff5463a5f9468eec8650caf3",
"sha256": "abbb4949818028282f19c9b4fd1c8dc66063d0b264c401bf8c22b3c1c0e65512"
},
"downloads": -1,
"filename": "paritydeals_sdk-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "c1686925ff5463a5f9468eec8650caf3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34869,
"upload_time": "2025-07-23T12:32:13",
"upload_time_iso_8601": "2025-07-23T12:32:13.121638Z",
"url": "https://files.pythonhosted.org/packages/b2/da/950fbc679f8f65b9a92b82dbb77c657bcc8f853f553a6c62f30c2d949c9a/paritydeals_sdk-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 12:32:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paritydeals",
"github_project": "paritydeals-python-sdk",
"github_not_found": true,
"lcname": "paritydeals-sdk"
}
