--- title: "Node SDK" description: "Documentation for the ParityDeals Node SDK" icon: 'node-js' --- ## Overview The ParityDeals Node SDK provides a convenient way to interact with the ParityDeals REST APIs from your Node application. Installation Install the ParityDeals SDK using npm or yarn: ```shell npm install @paritydeals/node-sdk ``` or ```shell yarn add @paritydeals/node-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). ```typescript # Example of setting it in your code (ensure you handle this securely) ACCESS_TOKEN = "__YOUR_API_KEY__" ``` ## Configuring the Client The SDK provides a main `ParityDeals` client class. You instantiate it directly with your configuration options. ```typescript const ACCESS_TOKEN: string = "YOUR_SECRET_ACCESS_TOKEN"; ``` #### How to Create a Client ```typescript import { ParityDeals } from '@paritydeals/node-sdk'; const client = new ParityDeals({ accessToken: ACCESS_TOKEN }); ``` ## Supported Functionalities The SDK currently supports the following operations: 1. [Customers](/api-reference/backend-integration/node-sdk#customers) 2. [Checkout](/api-reference/backend-integration/node-sdk#checkout) 3. [Entitlements](/api-reference/backend-integration/node-sdk#entitlements) 4. [Reporting](/api-reference/backend-integration/node-sdk#reporting) 5. [Subscriptions](/api-reference/backend-integration/node-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. --- ### Creates a new customer ```typescript const newCustomer = await client.customers.create({ customerId: "unique-customer-id-789", email: "new.node.customer@example.com", name: "Node SDK User", metadata: { source: "sdk_import", priority: "high" } }); ``` ```json { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", // Server-generated UUID "customerId": "unique-customer-id-789", "name": "Node SDK Use", "email": "new.node.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" } ``` **Required Parameters:** * `customerId` : 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` : The email address of the customer. Must be a valid email format. * `name` : The name of the customer. * `metadata` : 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` : The server-generated unique UUID for the customer record. * `customerId` : The client-provided customer identifier. * `name` : The customer's name. * `email` : The customer's email. * `details` : Any server-added details about the customer (typically read-only). * `metadata` : The metadata associated with the customer. * `createdOn` : ISO 8601 timestamp of when the customer was created. * `modifiedOn` : 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. ```typescript const updatedCustomer = await client.customers.update({ customerId: "unique-customer-id-789", name: "Node SDK User (Updated)", metadata: { tier: "premium_plus" } }); ``` ```json { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", // Server-generated UUID "customerId": "unique-customer-id-789", "name": "Node SDK User (Updated)", "email": "new.node.customer@example.com", "details": {}, // Or any server-added details "metadata": { "tier": "premium_plus" }, "createdOn": "2025-06-04T06:03:30.195790Z", "modifiedOn": "2025-06-04T06:03:30.195831Z" } ``` **Parameters:** **Required Parameters:** * `customerId` : 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` : The email address of the customer. Must be a valid email format. * `name` : The name of the customer. * `metadata` : 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` : The server-generated unique UUID for the customer record. * `customerId` : The client-provided customer identifier. * `name` : The customer's name. * `email` : The customer's email. * `details` : Any server-added details about the customer (typically read-only). * `metadata` : The metadata associated with the customer. * `createdOn` : ISO 8601 timestamp of when the customer was created. * `modifiedOn` : 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. This operation creates a new checkout session for a customer, allowing them to proceed with a purchase or subscription. ```typescript import { ParityDeals, CHARGE_PERIOD_CHOICES } from '@paritydeals/node-sdk'; const response = await client.checkout.createSession({ planIdentifier: "plan-pro-monthly", chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY, successUrl: "https://paritydeals.com/checkout/success", customerId: "cust_789", // Recommended, otherwise it will create a new customer }); ``` ```json { "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_b1sNi7D6u9iMCUFV1UZi9ZaiXKdOOmr3DCUW6XdCZIr5Id1F7#fid2cGd2ZndsdXsdjahsdkhsdhc%2FY2RpdmApJ3Zxd2x1YERmZmpwa3EnPydkZmZxWjRLZjV3X0BAckFBYGJKSEInKSdkdWxOYHwnPyd1blpxYHZxWjA0Tj1DSGdWRmwxYkdiMFxGQ29zf2BdTldOTGQzUlNqfWd9U1ZkanNHMlVnczxidEg0fFFqYVJNYzw8XEh2YVA8dkQ1bmA9NW5sS1c2PHE8hH89Q11Uf1E2NTVgY0M1Q0ZmYycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwc", "checkoutSessionId": "cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G", } ``` **Required Parameters:** * `planIdentifier` : The identifier of the specific plan the customer is checking out with. planIdentifier is mandatory. * `successUrl` : The URL to which the user will be redirected after a successful checkout. * `chargePeriod` : The billing cycle for the subscription. Must be one of: * `"ONE_TIME"` * `"MONTHLY"` * `"YEARLY"` * `"WEEKLY"` * `"DAILY"` * `"THREE_MONTHS"` * `"SIX_MONTHS"` **Optional Parameters:** * `offeringId` : The ID (uuid) of the offering the customer is checking out with. * `pricingTableId` : The id (uuid) of the pricing table being used for this checkout. (Considered only if `offeringId` is not provided) * `ruleId` : The id (uuid) of the pricing rule being applied. (Considered only if `offeringId` is not provided) * `customerId` : The ID of the customer initiating the checkout. (If not provided, a new customer will be created) * `features`: **Required**. A list of dictionaries, where each dictionary represents a feature and its desired quantity. Each dictionary **must** have two keys: * `"identifier"` : The unique identifier for the feature. * `"quantity"`: The desired quantity for this feature. * Example: `[{"identifier": "seats", "quantity": 10}, {"identifier": "api-calls-tier1", "quantity": 5000}]` * `ipAddress` : The IP Address of the customer, used for location based pricing. **Returns**: An instance of CreateCheckoutSessionResponse (Pydantic model), which includes: * `checkoutSessionId` : The unique ID for the created checkout session. * `checkoutUrl` : 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. ```typescript const hasAccess = await client.entitlements.hasAccess({ customerId: "cust_node_ent_123", featureId: "premium-reporting-node" }); ``` ```shell True ``` **Required Parameters**: * `customerId` : The unique identifier for the customer. * `featureId` : 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. ```typescript const response = await client.entitlements.getEntitlement({ customerId: "cust_node_ent_123", featureId: "premium-reporting-node" }); ``` ```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 } ] } ``` **Required Parameters**: * `customerId` : The unique identifier for the customer. * `featureId` : 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` : 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. ```typescript const response = await client.entitlements.getAllEntitlements({ customerId: "cust_node_ent_123" }); ``` ```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 } ] } ``` **Required Parameters**: * `customerId` : The unique identifier for the customer. **Returns**: * `customerId` : 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. ```typescript import { BEHAVIOUR_CHOICES } from '@paritydeals/node-sdk'; const response = await client.reporting.reportUsage({ value: 150, customerId: "customer_001", featureId: "seats", behaviour: BEHAVIOUR_CHOICES.SET }); ``` ```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" } ``` **Required Parameters**: * `value`: The usage value being reported. * `customerId` : The unique identifier for the customer associated with this usage. * `featureId` : 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`: The usage value that was recorded. * `customerId` : The customer ID associated with the usage. * `featureId` : The feature Identifier for which usage was recorded. * `behaviour` : The behaviour type ("SET" or "DELTA") that was processed. * `orgId` : The organization ID associated with this record, as determined by the server. * `eventName` : An internal event name generated by the server for this usage report (e.g., "aggregated.usage"). * `idempotencyKey` : A unique idempotency key generated by the server for this specific usage report instance. * `timestamp` : The server-generated UTC timestamp (str format) indicating when the usage report was processed. ## 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 ```typescript import { CHARGE_PERIOD_CHOICES } from '@paritydeals/node-sdk'; try: const response = await client.subscription.update({ subscriptionId: "sub_node_78058918", planIdentifier: "premium-plan-node", chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY }); except Exception as e: print(f"Error updating subscription: {e}") ``` ```json { "subscriptionId": "dffaf07e-4517-47db-ba3a-59a05aa2d465" } ``` **Required Parameters**: * `subscriptionId` : The unique identifier of the subscription to be updated. * `planIdentifier` : The identifier of the new plan. * `chargePeriod` : The new charging period for the subscription. Must be one of: * `"ONE_TIME"` * `"MONTHLY"` * `"YEARLY"` * `"WEEKLY"` * `"DAILY"` * `"THREE_MONTHS"` * `"SIX_MONTHS"` **Optional Parameters:** * `offeringId` : The ID of the new offering, if applicable. * `pricingTableId` : The ID of the new pricing table, if applicable. * `ruleId` : The ID of the new pricing rule, if applicable. * `ipAddress` : The IP Address of the customer, used for location based pricing. * `features`: A array of objects, where each dictionary represents a feature and its desired quantity to update for the subscription. Each dictionary **must** have two keys: * `"identifier"` : The unique identifier for the feature. * `"quantity"` : 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. ```typescript import { CANCELLATION_TYPES } from '@paritydeals/node-sdk'; const response = await client.subscription.cancel({ subscriptionId: "sub_node_78058918", cancellationType: CANCELLATION_TYPES.CURRENT_PERIOD_ENDS // cancellationDate: "2025-12-31" // Required if cancellationType is SPECIFIC_DATE }); ``` ```json { "message": "Subscription cancellation processed successfully." } ``` **Required Parameters**: * `subscriptionId` : The unique identifier of the subscription to be cancelled. * `cancellationType` : 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` : 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` : A confirmation message indicating the result of the cancellation request.