Overview

This library provides a Python client to interact with Stigg’s GraphQL API based on the operations the Stigg’s Node.js SDK is using under the hood. The ariadne-codegen code generator is used to generate a typesafe and async Python API client, which is based on httpx and pydantic.

Installing the SDK

The first step is to install the Stigg SDK as a dependency in your application using your application’s dependency manager:

pip install stigg-api-client-v2

Retrieving the full access key

In the Stigg app, go to Integrations > API keys. Copy the Full access key of the relevant environment.

Initializing the SDK

Import the Stigg client and initialize it with the API key. Synchronous client:

from stigg import Stigg

client = Stigg.create_client("STIGG_FULL_ACCESS_KEY")

Asynchronous client (asyncio):

from stigg import Stigg

client = Stigg.create_async_client("STIGG_FULL_ACCESS_KEY")

Provisioning customers

When a new customer is provisioned within your application (for example: as part of your registration or onboarding process), you should also provision them in Stigg. The customer’s billing information can also be passed to Stigg when a customer is created or updated. When Stigg is integrated with additional service, this information will be propagated to the active integrations. The billing information is not persisted on Stigg’s servers. You can optionally pass subscriptionParams to create subscription for that customer using a single operation. Doing so, will allow Stigg admins to override the requested subscription with no-code from the Stigg app using the product’s Customer Journey configuration.

data = await client.provision_customer(ProvisionCustomerInput(**{
  "refId": "customer-demo-123",
  "name": "Acme", 						# optional
  "email": "john@example.com", 	# optional - billing email address
  "couponRefId": "coupon-id", # optional
  "subscriptionParams": {
    "planId": "plan-revvenu-basic",
    "billingCountryCode": "DK"  # optional, required for price localization, must be in the ISO-3166-1 format
  },
  "billingInformation": { 		# optional
    "language": "en",
    "timezone": "America/New_York",
    "billingAddress": {
      "country": "US",
      "city": "New York",
      "state": "NY",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt. 1",
      "phoneNumber": "+1 212-499-5321",
      "postalCode": "10164"
    },
    "shippingAddress": {
      "country": "US",
      "city": "New York",
      "state": "NY",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt. 1",
      "phoneNumber": "+1 212-499-5321",
      "postalCode": "10164"
    }
  },
  "additionalMetaData": {			 # optional
    "key": "value"
  }   
}))

Show Result

{
    "provision_customer": {
        "customer": {
            "id": "customer-demo-123",
            "name": "Acme",
            "email": "john@example.com",
            "created_at": "2022-10-30T23:31:47.914Z",
            "updated_at": "2022-10-30T23:31:47.914Z",
            "promotional_entitlements": [],
            "has_payment_method": false,
            "coupon": null,
            "billing_id": null,
            "metadata": {
                "key": "value"
            }
        },
        "subscription_strategy_decision": "REQUESTED_PLAN",
        "subscription": {
            "id": "subscription-plan-revvenu-basic-f0c14f",
            "status": "ACTIVE",
            "metadata": null,
            "billing_id": null,
            "billing_link_url": null,
            "effective_end_date": null,
            "current_billing_period_end": "2022-11-30T23:31:48.112Z",
            "pricing_type": "FREE",
            "prices": [],
            "total_price": null,
            "plan": {
                "id": "plan-revvenu-basic"
            },
            "addons": [],
            "customer": {
                "id": "customer-id"
            }
        }
    }
}

Updating customers

Customer information can also be updated whenever you like assuming it already exists, for example: In order to update the customer’s email, you only need to send the new email value without the rest of the customer. Due to the fact that the customer’s billing information is not persisted on Stigg’s servers, in order to update it, the entire billing information object must be passed each time.

data = await client.update_customer(UpdateCustomerInput(
  **{
    "email": "john@example.com",
    "name": "Acme",
    "refId": "customer-id2",
    "billingInformation": {
      "payment_method_id": "pm_123123",
      "language": "en",
      "timezone": "America/New_York",
      "currency": "USD",
      "taxIds": [
        {"type": "...", "value": "..."}
      ],
    },
    "additionalMetaData": {
      "key": "value"
    }
  }
))

Show Result

{
    "update_customer": {
        "id": "customer-id2",
        "name": "Acme",
        "email": "john@example.com",
        "created_at": "2022-10-30T23:25:44.099Z",
        "updated_at": "2022-10-30T23:46:50.675Z",
        "promotional_entitlements": [],
        "has_payment_method": false,
        "coupon": null,
        "billing_id": null,
        "metadata": {
            "key": "value"
        }
    }
}

Getting customer data

data = await client.get_customer_by_id(GetCustomerByRefIdInput({
  "customerId": "customer-id2"
}))

Show Result

{
  "get_customer_by_ref_id": {
    "id": "customer-id2",
    "name": "Acme",
    "email": "john@example.com",
    "created_at": "2022-10-30T23:25:44.099Z",
    "updated_at": "2022-10-30T23:46:50.675Z",
    "promotional_entitlements": [],
    "has_payment_method": false,
    "coupon": null,
    "billing_id": null,
    "metadata": {
      "key": "value"
    }
  }
}

Listing customers active subscriptions

The get_active_subscriptions_list method returns a list of slim subscription data, for extended data for a specific subscription use get_subscription method.

data = await client.get_active_subscriptions_list(GetActiveSubscriptionsInput(
  **{
    "customerId": "CUSTOMER-ID",
    "resourceId": "RESOURCE-ID"   # optional - pass it to get subscription of specific resource 
  }
))

Show Result

{
  "get_active_subscriptions": [
    {
      "subscription_id": "subscription-plan-stigg-pro-28a241",
      "status": "ACTIVE",
      "start_date": "2022-09-20T09:00:14.000Z",
      "end_date": null,
      "effective_end_date": "2023-09-20T09:00:14.000Z",
      "current_billing_period_start": "2023-08-20T09:00:14.000Z",
      "current_billing_period_end": "2023-09-20T09:00:14.000Z",
      "billing_period": "MONTHLY",
      "additional_meta_data": {
        "internal_tier_id": "tier-gold"
      },
      "pricing_type": "PAID",
      "customer": {
        "customer_id": "customer-demo-01",
        "email": "user@example.com"
      },
      "paying_customer": {
        "customer_id": "customer-demo-01",
        "email": "user@example.com"
      },
      "plan": {
        "plan_id": "plan-stigg-pro",
        "display_name": "Pro",
        "description": "Full access to all Pro features",
        "product": {
          "ref_id": "product-main",
          "display_name": "Main Product",
          "downgrade_plan": {
            "ref_id": "plan-free",
            "display_name": "Free Plan"
          }
        }
      },
      "addons": [
        {
          "quantity": 3,
          "addon": {
            "addon_id": "addon-stigg-1"
          }
        }
      ],
      "prices": [
        {
          "billing_model": "FLAT_FEE",
          "price": {
            "billing_period": "MONTHLY",
            "price": {
              "amount": 99,
              "currency": "USD"
            }
          }
        }
      ],
      "total_price": {
        "sub_total": {
          "amount": 99,
          "currency": "USD"
        },
        "total": {
          "amount": 99,
          "currency": "USD"
        }
      }
    }
  ]
}

Getting a subscription

To retrieve extended subscription data:

data = await client.get_subscription(GetSubscriptionInput(
  **{
    "subscriptionId": "SUBSCRIPTION-ID",
  }
))

Show Result

{
  "get_subscription": {
    "id": "subscription-plan-revvenu-basic-169747",
    "status": "ACTIVE",
    "start_date": "2022-10-30T23:25:44.258Z",
    "end_date": null,
    "trial_end_date": null,
    "cancellation_date": null,
    "effective_end_date": null,
    "current_billing_period_end": "2022-11-30T23:25:44.258Z",
    "metadata": null,
    "billing_id": null,
    "billing_link_url": null,
    "prices": [],
    "total_price": null,
    "pricing_type": "FREE",
    "plan": {
      "id": "plan-revvenu-basic",
      "display_name": "Basic",
      "description": null,
      "metadata": null,
      "product": {
        "id": "product-revvenu",
        "display_name": "Revvenu",
        "description": null
      },
      "base_plan": null,
      "entitlements": [
        {
          "usage_limit": 3,
          "has_unlimited_usage": null,
          "feature_id": "6d15081c-a3dc-4091-ab8c-9f25dc366173",
          "reset_period": null,
          "feature": {
            "id": "feature-01-templates",
            "feature_type": "NUMBER",
            "meter_type": "Fluctuating",
            "feature_units": "template",
            "feature_units_plural": "templates",
            "display_name": "Templates",
            "description": null
          }
        },
        {
          "usage_limit": 4,
          "has_unlimited_usage": null,
          "feature_id": "08a4a367-4286-4dfd-bfae-6c77a723e80c",
          "reset_period": "MONTH",
          "feature": {
            "id": "feature-02-campaigns",
            "feature_type": "NUMBER",
            "meter_type": "Incremental",
            "feature_units": "campaign",
            "feature_units_plural": "campaigns",
            "display_name": "Campaigns",
            "description": null
          }
        }
      ],
      "inherited_entitlements": [],
      "compatible_addons": [],
      "prices": [],
      "pricing_type": "FREE",
      "default_trial_config": null
    },
    "addons": [],
    "payment_collection": "NOT_REQUIRED", // status of the payment collection of the subscription - can be either 'NOT_REQUIRED', 'FAILED', 'ACTION_REQUIRED' or 'PROCESSING'
    "latest_invoice": {
      "billing_id": "invoice-01", // ID of the invoice of the billing provider
      "status": "PAID", // can be either 'OPEN', 'CANCELED' or 'PAID'
      "created_at": "2023-08-22T11:27:41.000Z",
      "updated_at": "2023-08-22T11:27:44.608Z",
      "requires_action": false, // indicate of the payment requires action to complete the payment
      "payment_url": "https://...", // payment url that can be sent to the customer to complete the payment
      "payment_secret": "secret-01", // secret to be used to initiate next action with billing provider
      "error_message": "", // optinal error message, if the status is FAILED
    }
  }
}

Provision subscriptions

When a customer subscribes to a new plan (for example: during an upgrade from a free plan to a paid plan, or downgrade from a higher tier to a lower tier), a subscription needs to be created in Stigg. When provisioning of a paid subscription is attempted, Stigg is integrated with a billing solution and payment details have not been previously provided by the customer, Stigg will auto-magically redirect customers to a the billing solution’s checkout page. After the customer enters the required payment details in the presented checkout page, the relevant subscription will be created in both Stigg and the billing solution. When no payment is required or when Stigg is not integrated with a billing solution, the subscription will be immediately created in Stigg. When a customer subscribes to a new plan (free, paid, trial, etc.), provision a subscription in Stigg. The provision result can be a successfully created subscription, or a redirect link to stripe checkout in case payment is needed.

data = await client.provision_subscription(ProvisionSubscriptionInput(
    **{
        "customerId": "customer-id",
        "planId": "plan-revvenu-basic",
        "resourceId": "resource-01",  # optional, required for multiple subscription for same product
        "billingPeriod": "MONTHLY",   # optional, required for paid subscriptions
        "billableFeatures": [{                # optional, required for plans with per-unit pricing
          "featureId": "feature-01-templates",
          "quantity": 2
        }],
        "addons": [                                       # optional
            {
                "addonId": "addon-extra-stuff",
                "quantity": 2
            }
        ],
        "entitlements": [                                 # optional, for custom plans (feature + credit)
            {
                "feature": {
                    "featureId": "feature-seats",
                    "usageLimit": 50
                }
            },
            {
                "credit": {
                    "customCurrencyId": "currency-api-credits",
                    "amount": 50000,
                    "cadence": "MONTH"  # MONTH or YEAR
                }
            }
        ],
        "billingCountryCode": "DK",   # optional, required for price localization, must be in the ISO-3166-1 format
          "awaitPaymentConfirmation": True,
          "billingInformation": {    # optional
            "couponId": "your coupon id" 
          },
        "additionalMetaData": {               # optional
            "key": "value"
        }
    }
))

Show Success result

{
  "provision_subscription": {
    "checkout_url": "https:\/\/your-success-url.com",
    "status": "SUCCESS",
    "subscription": {
      "id": "subscription-plan-revvenu-essentials-93981d",
      "status": "PAYMENT_PENDING",
      "metadata": null,
      "billing_id": null,
      "billing_link_url": null,
      "effective_end_date": null,
      "current_billing_period_end": "2022-12-17T15:26:01.291Z",
      "pricing_type": "PAID",
      "prices": [
        {
          "billing_model": "FLAT_FEE",
          "price": {
            "billing_period": "MONTHLY",
            "price": {
              "amount": 99,
              "currency": "USD"
            }
          }
        }
      ],
      "total_price": {
        "sub_total": {
          "amount": 20,
          "currency": "USD"
        },
        "total": {
          "amount": 20,
          "currency": "USD"
        }
      },
      "plan": {
        "id": "plan-revvenu-essentials"
      },
      "addons": [
        
      ],
      "customer": {
        "id": "customer-demo-02"
      },
      "payment_collection": "NOT_REQUIRED",
      "latest_invoice": {
        "billing_id": "invoice-01",
        "status": "PAID",
      }
    }
  }
}

Show Payment Requires action

{
  "provision_subscription": {
    "status": "SUCCESS",
    "subscription": {
      "payment_collection": "ACTION_REQUIRED",
      "latest_invoice": {
        "payment_url": "https...",
        "payment_secret": "secret",
      }
    }
  }
}

Show Payment failed

{
  "provision_subscription": {
    "status": "SUCCESS",
    "subscription": {
      "payment_collection": "FAILED",
      "latest_invoice": {
        "payment_url": "https...",
        "error_message": "no sufficient funds"
      }
    }
  }
}

Show Payment Requires checkout

{
  "provision_subscription": {
    "checkout_url": "https:\/\/checkout.stripe.com\/c\/pay\/cs_test_a1ZW8HpF4G7hV6w9Q9hV7MGYpzBU2BPpt6RJRZXE2PC7WyxRHQKqQ2UvDj#fidkdWxOYHwnPyd1blpxYHZxWjA0Tzx1TlNJSHxCYEZGd1BHPU1kM0JAXVFHfXdrREhnQ3VJdldAS1MwZjRkNGxxcWBVf09SSE0zRzBcYTN3cXNkbFdMQnI0V3ZrN0toSGc3NnB9QEdBPVJMNTVzM3NpdnVDSycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYCkndnF3bHVgRGZmanBrcSc%2FJ2RmZnFaNE5MdGtyQDRiU1E3f3JfUyd4JSUl",
    "status": "PAYMENT_REQUIRED",
    "subscription": null
  }
}

A customer can have both a non-trial (free or paid) subscription and trial subscription to different plans of the same product in parallel - this logic allows customers to trial a higher tier plan, while still paying for an existing plan.
When the customer has a trial subscription for plan X of product A and a new subscription is created for the same plan, the new subscription will be created as as non-trial (paid) subscription - this logic follows an upgrade flow of a trial subscription to a paid subscription of a specific plan.
Except in the above mentioned cases, when a customer has an active subscription for product X, and another subscription for the same product is created with start date S, the existing subscription will automatically be cancelled and the new subscription will start on start date S.
It’s also possible to explicitly skip the trial period of the selected plan by providing the skipTrial: true parameter to the provisionSubscription() method.

Updating subscriptions

Updating an existing subscription, this can be used to update the feature quantity that the customer is subscribed for or the add-ons.

data = await client.update_subscription(UpdateSubscriptionInput(
  **{
    "refId": "subscription-plan-revvenu-growth-589879",
    "billableFeatures": [{
      "featureId": "feature-01-templates",
      "quantity": 2
    }],
  }
))

Show Result

{
    "update_subscription": {
        "id": "subscription-plan-revvenu-growth-589879",
        "status": "ACTIVE",
        "metadata": null,
        "billing_id": "sub_1LxD4TE1gVT2zwZVSav7tZvC",
        "billing_link_url": "https:\/\/dashboard.stripe.com\/test\/subscriptions\/sub_1LxD4TE1gVT2zwZVSav7tZvC",
        "effective_end_date": null,
        "current_billing_period_end": "2022-11-26T17:07:17.000Z",
        "pricing_type": "PAID",
        "prices": [
            {
                "usage_limit": 2,
                "price": {
                    "billing_model": "PER_UNIT",
                    "billing_period": "MONTHLY",
                    "price": {
                        "amount": 1,
                        "currency": "USD"
                    },
                    "feature": {
                        "id": "feature-01-templates",
                        "feature_type": "NUMBER",
                        "meter_type": "Fluctuating",
                        "feature_units": "template",
                        "feature_units_plural": "templates",
                        "display_name": "Templates",
                        "description": null
                    }
                }
            }
        ],
        "total_price": {
            "sub_total": {
                "amount": 17,
                "currency": "USD"
            },
            "total": {
                "amount": 17,
                "currency": "USD"
            }
        },
        "plan": {
            "id": "plan-revvenu-growth"
        },
        "addons": [
            {
                "quantity": 3,
                "addon": {
                    "id": "addon-10-campaigns"
                }
            }
        ],
        "customer": {
            "id": "customer-demo-01"
        },
        "payment_collection": "NOT_REQUIRED", // status of the payment collection of the subscription - can be either 'NOT_REQUIRED', 'FAILED', 'ACTION_REQUIRED' or 'PROCESSING'
        "latest_invoice": {
          "billingId": "invoice-01", // ID of the invoice of the billing provider
          "status": "PAID", // can be either 'OPEN', 'CANCELED' or 'PAID'
          "created_at": "2023-08-22T11:27:41.000Z",
          "updated_at": "2023-08-22T11:27:44.608Z",
          "requires_action": false, // indicate of the payment requires action to complete the payment
          "payment_url": "https://...", // payment url that can be sent to the customer to complete the payment
          "payment_secret": "secret-01", // secret to be used to initiate next action with billing provider
          "error_message": "", // optinal error message, if the status is FAILED
        }
    }
}

Cancel subscription

data = await client.cancel_subscription(SubscriptionCancellationInput(
  **{
    "subscriptionRefId": "subscription-plan-revvenu-growth-589879",
    "subscriptionCancellationTime":  "IMMEDIATE"
  }
))

Show Result

{
    "cancel_subscription": {
        "id": "subscription-plan-revvenu-growth-589879",
        "status": "CANCELED",
        "metadata": null,
        "billing_id": "sub_1LxD4TE1gVT2zwZVSav7tZvC",
        "billing_link_url": "https:\/\/dashboard.stripe.com\/test\/subscriptions\/sub_1LxD4TE1gVT2zwZVSav7tZvC",
        "effective_end_date": "2022-10-30T23:54:38.582Z",
        "current_billing_period_end": "2022-11-26T17:07:17.000Z",
        "pricing_type": "PAID",
        "prices": [
            {
                "usage_limit": 2,
                "price": {
                    "__typename": "Price",
                    "billing_model": "PER_UNIT",
                    "billing_period": "MONTHLY",
                    "price": {
                        "amount": 1,
                        "currency": "USD"
                    },
                    "feature": {
                        "__typename": "Feature",
                        "id": "feature-01-templates",
                        "feature_type": "NUMBER",
                        "meter_type": "Fluctuating",
                        "feature_units": "template",
                        "feature_units_plural": "templates",
                        "display_name": "Templates",
                        "description": null
                    }
                }
            }
        ],
        "total_price": {
            "sub_total": {
                "amount": 17,
                "currency": "USD"
            },
            "total": {
                "amount": 17,
                "currency": "USD"
            }
        },
        "plan": {
            "id": "plan-revvenu-growth"
        },
        "addons": [
            {
                "quantity": 3,
                "addon": {
                    "id": "addon-10-campaigns"
                }
            }
        ],
        "customer": {
            "id": "customer-demo-01"
        }
    }
}

Subscription cancellation will take place according to the defined product behavior.

Getting the entitlement of a customer for a specific feature

Used to check if the customer has access to a feature, the usage limit, and the current usage.

resp = await client.get_entitlement(FetchEntitlementQuery(
  **{
    "customerId": "customer-id",
    "featureId": "feature-01-templates",
    "options": {  
      "requestedUsage": 10  
    },
    "resourceId": "resource-01",  # optional, pass it to get entitlement of specific resource
  }
))

if resp.entitlement.is_granted:
  # customer has access to the feature
  pass
else:
  # access denied
  pass

Show Result

{
        "entitlement": {
            "is_granted": true,
            "access_denied_reason": null,
            "customer_id": "eb741bdb-4ca7-416f-a6f1-49483ed2a2e2",
            "usage_limit": 3,
            "has_unlimited_usage": false,
            "current_usage": 0,
            "requested_usage": null,
            "usage_period_anchor": null,
            "usage_period_start": null,
            "usage_period_end": null,
            "reset_period": null,
            "feature": {
                "id": "feature-01-templates",
                "feature_type": "NUMBER",
                "meter_type": "Fluctuating",
                "feature_units": "template",
                "feature_units_plural": "templates",
                "display_name": "Templates",
                "description": null
            },
            "reset_period_configuration": null
        }
}

Getting all of the entitlements of a customer

Used to check to what features the customer has access to, the usage limit , and the current usage of each entitlement.

data = await client.get_entitlements_state(FetchEntitlementsQuery(
  **{
    "customerId": "customer-id",
    "resourceId": "resource-01",  # optional, pass it to get entitlement of specific resource
  }
))

Show Result

{
    "data": {
        "entitlementsState": {
            "entitlements": [
              {
                  "feature": {
                      "ref_id": "feature-03-custom-domain",
                      "display_name": "Custom domain",
                      "feature_units": null,
                      "feature_units_plural": null,
                      "feature_type": "BOOLEAN",
                      "meter_type": "None",
                      "description": null
                  },
                  "current_usage": 0,
                  "customer_id": "96ed6019-031a-4c52-bc41-b8fa3b5d86c5",
                  "usage_limit": null,
                  "has_unlimited_usage": false,
                  "usage_period_anchor": null,
                  "usage_period_start": null,
                  "usage_period_end": null,
                  "reset_period": null
              },
              {
                  "feature": {
                      "ref_id": "feature-04-analytics",
                      "display_name": "Analytics",
                      "feature_units": null,
                      "feature_units_plural": null,
                      "feature_type": "BOOLEAN",
                      "meter_type": "None",
                      "description": null
                  },
                  "current_usage": 0,
                  "customer_id": "96ed6019-031a-4c52-bc41-b8fa3b5d86c5",
                  "usage_limit": null,
                  "has_unlimited_usage": false,
                  "usage_period_anchor": null,
                  "usage_period_start": null,
                  "usage_period_end": null,
                  "reset_period": null
              },
              {
                  "feature": {
                      "ref_id": "feature-01-templates",
                      "display_name": "Templates",
                      "feature_units": "Template",
                      "feature_units_plural": "Templates",
                      "feature_type": "NUMBER",
                      "meter_type": "Fluctuating",
                      "description": null
                  },
                  "current_usage": 3,
                  "customer_id": "96ed6019-031a-4c52-bc41-b8fa3b5d86c5",
                  "usage_limit": 5,
                  "has_unlimited_usage": false,
                  "usage_period_anchor": null,
                  "usage_period_start": null,
                  "usage_period_end": null,
                  "reset_period": null
              },
              {
                  "feature": {
                      "ref_id": "feature-02-campaigns",
                      "display_name": "Campaigns",
                      "feature_units": "Campaign",
                      "feature_units_plural": "Campaigns",
                      "feature_type": "NUMBER",
                      "meter_type": "Incremental",
                      "description": null
                  },
                  "current_usage": 10,
                  "customer_id": "96ed6019-031a-4c52-bc41-b8fa3b5d86c5",
                  "usage_limit": 12,
                  "has_unlimited_usage": false,
                  "usage_period_anchor": "2023-02-21T00:00:00Z",
                  "usage_period_start": "2023-11-21T00:00:00Z",
                  "usagePeriodEnd": "2023-12-21T00:00:00Z",
                  "reset_period": "MONTH"
              }
            ],
            "accessDeniedReason": null
        }
    }
}

Reporting usage measurements to Stigg

The Stigg SDK allows you to report usage measurements for metered features. The reported usage will be used to track, limit and bill the customer’s usage of metered features. Stigg supports metering of usage from the following data sources:

Calculated usage - usage that has been aggregated and calculated by your application. This type is useful for features, such as: seats.
Raw events - raw events from your application, which Stigg filters and aggregates aggregate to calculate customer usage. This type is useful for features, such as: monthly active users (MAUs).

More details about Stigg’s metering and aggregation capabilities can be found here:

Stigg's metering and aggregation capabilities

Reporting of measurements to Stigg should be done only after the relevant resources have been provisioned in your application.
To ensure that the provisioned resources are aligned with the measurements that are reported to Stigg, ensure that customers are not allowed to allocate new resources until an acknowledgement about the processed measurement is received from the Stigg backend.

Validating that a measurement was successfully reported to Stigg is also possible in the customer details section of the relevant customer in the Stigg app.

Calculated usage

data = await client.report_usage(ReportUsageInput(
    **{
        "value": 5,
        "customerId": "customer-id",
        "featureId": "feature-02-campaigns",
        "resourceId": "resource-01",  # optional, pass it to report usage for specific resource
    }
  ))

By default, the value reported should represent the change in usage of the feature, for example user added 2 more seats then the report usage call should have the value of 2. In some cases, it’s more useful to set the usage to some value instead of reporting the change value, it’s possible by passing the updateBehavior parameter:

data = await client.report_usage(ReportUsageInput(
    ** {
        "value": 5,
        "customerId": "customer-id",
        "featureId": "feature-02-campaigns",
        "updateBehavior": "SET",
        "resourceId": "resource-01",  # optional, pass it to report usage for specific resource
    }
))

Show Result

{
    "report_usage": {
        "id": "d723d1c6-64fa-4a8b-aa2d-a6dc57e13804"
    }
}

Raw events

// report event of a user login
data = await client.report_event(UsageEventsReportInput(
    ** {
					"usageEvents": [{
                  					"customerId": "customer-test-id",
							    					"resourceId": "resource-01",      // optional, pass it to report event for specific resource
							    					"eventName": "user_login",
							    					"idempotencyKey": "227c1b73-883a-457b-b715-6ba5a2c69ce4",
							    					"dimensions": {
																						"user_id": "user-01",
													    							"user_email": "john@example.com"
												    							},
														"timestamp": "2022-10-26T15:01:55.768Z" // optional, pass it to report event with specific timestamp
               						}]
    	 }
));

It’s also possible to send a batch of events in one invocation. To do so, simply pass an array of events to the reportEvent method.

Getting available coupons

data = await client.get_coupons()

Show Result

{
    "coupons": {
        "edges": [
            {
                "node": {
                    "__typename": "Coupon",
                    "id": "coupon-vip",
                    "name": "VIP",
                    "description": null,
                    "type": "PERCENTAGE",
                    "discount_value": 20,
                    "metadata": null,
                    "created_at": "2022-10-26T15:01:55.768Z",
                    "updated_at": "2022-10-26T15:01:56.432Z",
                    "billing_id": "YSkVNwUu",
                    "billing_link_url": "https:\/\/dashboard.stripe.com\/test\/coupons\/YSkVNwUu",
                    "status": "ACTIVE"
                }
            }
        ]
    }
}

Granting promotional entitlements

You can grant promotional entitlements for customers using the grant_promotional_entitlements method.

data = await client.grant_promotional_entitlements(GrantPromotionalEntitlementsInput(**{
    "customer_id": "customer-id",
    "promotional_entitlements": [
      {
        "feature_id": "feature-04-analytics",
        "period": "ONE_MONTH",
        "reset_period": "MONTH",
            "monthly_reset_period_configuration": {
              "according_to": "StartOfTheMonth"
            },
      },
      {
        "feature_id": "feature-03-memory",
        "period": "CUSTOM",
        "custom_end_date": "2023-10-26T15:01:55.768Z",
        "usage_limit": 100
      }
    ]
  }
))

Show Result

{
    "grant_promotional_entitlements": [
      {
        "feature_id": "feature-04-analytics",
        "period": "ONE_MONTH"
      },
      {
        "usage_limit": 100,
        "feature_id": "feature-03-memory",
        "end_date": "2023-10-26T15:01:55.768Z"
      }
    ]
}

Revoking promotional entitlements

You can revoke promotional entitlements from customer using the revoke_promotional_entitlements method.

data = await client.set_promotional_entitlements(RevokePromotionalEntitlementInput(**{
    "customer_id": "customer-id",
    "feature_id": "feature-04-analytics",	
}))

Show Result

{
    "id": "210016fa-f482-40c0-9e28-3818eb0332d3"
}

Estimate subscription cost

You can estimate the subscription cost using the estimateSubscription method. This can help the customer to understand the costs before paying.

data = await client.request(EstimateSubscriptionInput(
    ** {
        "customerId": "customer-demo-01",
        "billingPeriod": "MONTHLY",
        "planId": "plan-revvenu-essentials",
      	"billableFeatures": [{								# optional, required for plans with per-unit pricing
          "featureId": "feature-01-templates",
          "quantity": 2
        }],
        "addons": [														# optional
            {
                "addonId": "addon-10-campaigns",
                "quantity": 2
            }
        ],
        "billingCountryCode": "DK"  # optional, required for price localization, must be in the ISO-3166-1 format
        "resourceId": "resource-01",  # optional, required for multiple subscription for same product
    }
))

Show Result

{
    "estimate_subscription": {
        "sub_total": {
            "amount": 30,
            "currency": "USD"
        },
        "total": {
            "amount": 30,
            "currency": "USD"
        },
        "billing_period_range": {
            "start": "2022-10-31T00:26:06.028Z",
            "end": "2022-11-30T00:26:06.028Z"
        },
        "proration": null
    }
}

You can also estimate the cost of updating an existing subscription using the updateSubscription method, which also returns a breakdown of the proration amounts:

data = await client.estimate_subscription_update(EstimateSubscriptionUpdateInput(
  ** {
    "subscriptionId": "subscription-plan-revvenu-growth-dfe598",
    "billableFeatures": [{
      "featureId": "feature-01-templates",
      "quantity": 7
    }],
    "addons": [
      {"addonId": "addon-10-campaigns", "quantity": 2 }
    ]
  }
))

Show Result

{
    "data": {
        "estimate_subscription_update": {
            "sub_total": {
                "amount": 7,
                "currency": "USD"
            },
            "total": {
                "amount": 7,
                "currency": "USD"
            },
            "billing_period_range": {
                "start": "2022-10-26T17:07:17.000Z",
                "end": "2022-11-26T17:07:17.000Z"
            },
            "proration": {
                "proration_date": "2022-10-26T17:08:23.000Z",
                "credit": {
                    "amount": -10,
                    "currency": "USD"
                },
                "debit": {
                    "amount": 17,
                    "currency": "USD"
                }
            }
        }
    }
}

Governance

Stigg Governance lets your enterprise customers control AI usage and credit spend across their organizations. The governance API is a REST API — use httpx (already installed as a transitive dependency of the SDK) to call it.

Check

Call check before allowing consumption. Returns hasAccess: true when every budget in the hierarchy allows the request.

import httpx
import os

GOVERNANCE_BASE_URL = os.environ["GOVERNANCE_API_URL"]
GOVERNANCE_HEADERS = {
    "Authorization": f"Bearer {os.environ['GOVERNANCE_ACCESS_TOKEN']}",
    "x-stigg-account-id": os.environ["STIGG_ACCOUNT_ID"],
    "x-stigg-environment-id": os.environ["STIGG_ENVIRONMENT_ID"],
}

async with httpx.AsyncClient() as http:
    response = await http.post(
        f"{GOVERNANCE_BASE_URL}/owners/cus-acme/check",
        headers=GOVERNANCE_HEADERS,
        json={
            "entityIds": ["team-eng"],
            "capabilityId": "ai-tokens",
            "requestedAmount": 1000,
        },
    )
    report = response.json()
    if not report["hasAccess"]:
        raise Exception("Usage limit reached")

Ingest

Call ingest after consuming to increment the usage counter.

async with httpx.AsyncClient() as http:
    await http.post(
        f"{GOVERNANCE_BASE_URL}/owners/cus-acme/ingest",
        headers=GOVERNANCE_HEADERS,
        json={
            "events": [
                {"entityIds": ["team-eng"], "capabilityId": "ai-tokens", "amount": 1250},
            ],
        },
    )

For the full check-then-ingest pattern, provisioning entities, setting budgets, and querying the governance tree, see Governance.

Integration guides

Quick start guides

I want to...

Python

Overview

Installing the SDK

Retrieving the full access key

Initializing the SDK

Provisioning customers

Updating customers

Getting customer data

Listing customers active subscriptions

Getting a subscription

Provision subscriptions

Updating subscriptions

Cancel subscription

Getting the entitlement of a customer for a specific feature

Getting all of the entitlements of a customer

Reporting usage measurements to Stigg

Stigg's metering and aggregation capabilities

Calculated usage

Raw events

Getting available coupons

Granting promotional entitlements

Revoking promotional entitlements

Estimate subscription cost

Governance

Check

Ingest

Full SDK reference

Python SDK reference

SDK changelog

Python SDK changelog

​Overview

​Installing the SDK

​Retrieving the full access key

​Initializing the SDK

​Provisioning customers

​Updating customers

​Getting customer data

​Listing customers active subscriptions

​Getting a subscription

​Provision subscriptions

​Updating subscriptions

​Cancel subscription

​Getting the entitlement of a customer for a specific feature

​Getting all of the entitlements of a customer

​Reporting usage measurements to Stigg

Stigg's metering and aggregation capabilities

​Calculated usage

​Raw events

​Getting available coupons

​Granting promotional entitlements

​Revoking promotional entitlements

​Estimate subscription cost

​Governance

​Check

​Ingest

​Full SDK reference

Python SDK reference

​SDK changelog

Python SDK changelog

Overview

Installing the SDK

Retrieving the full access key

Initializing the SDK

Provisioning customers

Updating customers

Getting customer data

Listing customers active subscriptions

Getting a subscription

Provision subscriptions

Updating subscriptions

Cancel subscription

Getting the entitlement of a customer for a specific feature

Getting all of the entitlements of a customer

Reporting usage measurements to Stigg

Calculated usage

Raw events

Getting available coupons

Granting promotional entitlements

Revoking promotional entitlements

Estimate subscription cost

Governance

Check

Ingest

Full SDK reference

SDK changelog