In this example, we’ll set up a 30-day trial that ends when either the time limit expires or the customer runs out of credits, whichever comes first. Customers can upgrade to a paid plan at any time by adding a payment method.The trial works as follows:
Customers receive 1,000 free credits when they sign up. These credits expire after 30 days.
The trial ends when the customer runs out of credits or when 30 days have elapsed, whichever comes first.
Customers can use your product while they have available credits. When credits are depleted, access is blocked.
Customers are not invoiced during the trial. Invoices only occur after they add a payment method and upgrade to the paid plan.
When a customer adds a payment method, they immediately upgrade to a $20/month Pro plan that includes 20 credits per month. Additional credits can be purchased on-demand or via automatic top-ups.
Use separate plans for trial and paid tiers. This provides clear visibility into trial vs paid customers and ensures credits persist through the upgrade process.
Core approach
Two-plan model
Create two separate plans in Orb:
Trial plan: No recurring charge, no credit allocation. Acts as a marker for trial customers and defines the trial period (30 days).
Pro plan: $20/month recurring charge with a 20-credit monthly allocation. This is the paid tier customers upgrade to.
The trial plan does not include a credit allocation. Instead, you grant credits separately using the ledger entry API. This ensures credits persist when customers upgrade from trial to paid.
Credits granted via plan allocations expire when you change or cancel the subscription. Credits granted via the ledger entry API persist across plan changes and only expire based on their configured expiration date.
Send usage events as customers consume credits and configure your billable metric to draw down from the prepaid credit balance.
Prerequisites
Before starting a customer on a trial, set up the following:
Do not block access based solely on the webhook. Webhook delivery order is not guaranteed. The customer may have purchased credits between depletion and webhook delivery.Instead, query the customer’s current balance using the fetch credit balance API when you receive the webhook:
balance = orb_client.customers.credits.fetch_by_external_id( external_customer_id="customer-18940", currency="credits", include_all_blocks=False # Only check currently active blocks)if balance["balance"] == 0: # Block access in your system block_customer_access("customer-18940")
If the balance is 0, block access in your application. Update a status field in your database that your product checks before allowing usage.
End trial early
If the customer has depleted credits and has not added a payment method, end the trial:
# Check if customer has payment methodcustomer = orb_client.customers.fetch_by_external_id( external_customer_id="customer-18940")if not customer.get("payment_provider_id"): # No payment method, cancel subscription orb_client.subscriptions.cancel( subscription_id=subscription["id"], cancel_option="immediate" )
Handling trial expiration
30-day limit webhook
When 30 days elapse, Orb automatically cancels the subscription (based on the end_date you set). You’ll receive a subscription.ended webhook:
When you receive this webhook, check if the customer has upgraded to a paid plan:
# List customer's active subscriptionssubscriptions = orb_client.subscriptions.list( external_customer_id="customer-18940", status="active")# Check if customer has an active Pro subscriptionhas_active_paid_sub = any( sub["plan"]["external_plan_id"] == "pro" for sub in subscriptions["data"])if not has_active_paid_sub: # Trial expired without upgrade, block access block_customer_access("customer-18940")
Upgrading to paid plan
When a customer wants to upgrade, collect payment information using Stripe’s payment method collection flows. See Stripe’s save and reuse payment methods documentation. Once the payment method is saved as the customer’s default in Stripe, Orb syncs it automatically.
Schedule plan change
When the customer adds a payment method, upgrade them immediately to the Pro plan:
Set change_option=immediate to upgrade right away. Set billing_cycle_alignment=plan_change_date to reset the billing cycle to start today and charge the full $20 monthly fee immediately.This creates an invoice for $20 and grants the customer their first 20-credit monthly allocation.
Credits granted during the trial persist through the upgrade because you granted them via the ledger entry API, not as a plan allocation. The customer keeps any remaining trial credits plus receives their first 20-credit monthly allocation from the Pro plan.
Preventing double trials
Check subscription history
Before creating a trial subscription, verify the customer hasn’t already had a trial:
# Fetch subscription schedule to see plan historyschedule = orb_client.subscriptions.fetch_schedule( subscription_id=subscription["id"])# Check if customer was ever on trial planhad_trial = any( phase["plan"]["external_plan_id"] == "trial" for phase in schedule)if had_trial: # Customer already had trial, don't create another raise Exception("Customer already used trial")
Alternatively, maintain a had_trial boolean in your database when you create the first trial subscription.
Subscription continuity
When a customer upgrades from trial to paid, Orb maintains the same subscription resource. The subscription ID remains constant; only the plan changes. This means:
A customer can only have one subscription lifecycle
Plan changes don’t reset trial eligibility
Subscription history provides a complete audit trail
To check if a customer ever had a trial, list their subscriptions and examine the plan history via the fetch schedule endpoint.
Manual operations
Extending trials
Extend a trial by updating the subscription’s end_date:
orb_client.subscriptions.update( subscription_id=subscription["id"], end_date="2025-04-15T23:59:59Z" # Extend by one week)
If you also want to extend the credit expiration, create a new ledger entry with updated credits or modify the existing block’s expiration.
Compensatory credits
Grant additional credits during the trial without charges:
orb_client.customers.credits.ledger.create_entry_by_external_id( external_customer_id="customer-18940", entry_type="increment", amount=500, currency="credits", per_unit_cost_basis="0.00", description="Compensatory credits for service interruption", expiry_date="2025-04-08T23:59:59Z")
Set per_unit_cost_basis to $0.00 to avoid invoicing. Use the description field to document the reason for the grant.
Was this page helpful?
{"docsConfig":{"theme":"palm","$schema":"https://mintlify.com/docs.json","name":"Orb","colors":{"primary":"#15003F","light":"#7DD3FC","dark":"#15003F"},"logo":{"light":"https://mintcdn.com/orb-9bba378a/LPn-ELJYNR-oFxhG/logo/orb-dark.svg?fit=max\u0026auto=format\u0026n=LPn-ELJYNR-oFxhG\u0026q=85\u0026s=9fbf232788a0bfab91e460473924a06f","dark":"https://mintcdn.com/orb-9bba378a/LPn-ELJYNR-oFxhG/logo/orb-light.svg?fit=max\u0026auto=format\u0026n=LPn-ELJYNR-oFxhG\u0026q=85\u0026s=7d375c8ed123a3f10f67ebef1346f66f"},"favicon":"https://mintcdn.com/orb-9bba378a/LPn-ELJYNR-oFxhG/logo/orb.svg?fit=max\u0026auto=format\u0026n=LPn-ELJYNR-oFxhG\u0026q=85\u0026s=7f05ef56022577fa316499a16c91db8e","api":{"playground":{"display":"simple"},"mdx":{"auth":{"method":"bearer"},"server":"https://api.withorb.com/v1"}},"navbar":{"links":[{"href":"https://support.withorb.com","label":"Support"}],"primary":{"type":"button","label":"Orb dashboard","href":"https://app.withorb.com"}},"footer":{"socials":{"x":"https://x.com/useOrb","github":"https://github.com/orbcorp","linkedin":"https://linkedin.com/company/orbhq"}},"integrations":{"gtm":{"tagId":"GTM-NVW7HVV"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"Changelog","icon":"newspaper","color":{"light":"#15003F","dark":"#F9FAFB"},"href":"https://changelog.withorb.com"},{"anchor":"Status","icon":"signal","color":{"light":"#15003F","dark":"#F9FAFB"},"href":"https://status.withorb.com"},{"anchor":"Blog","icon":"book-open-cover","color":{"light":"#15003F","dark":"#F9FAFB"},"href":"https://www.withorb.com/blog"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"orb-9bba378a","hasAudioNarration":false,"actualSubdomain":"orb-9bba378a","customDomains":["docs.withorb.com"],"gitSource":{"type":"github","owner":"orbcorp","repo":"dev-docs","deployBranch":"prod-docs","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"edits":true,"issues":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6afb4cc03b9b1d7bae8764c4","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"default","tag":"API reference","count":266},{"language":"default","tag":"Documentation","count":102},{"language":"default","tag":"Webhooks","count":89},{"language":"default","tag":"Subscription","count":37},{"language":"default","tag":"Integrations","count":33},{"language":"default","tag":"Plan","count":30},{"language":"default","tag":"Integrations and exports","count":28},{"language":"default","tag":"Customer","count":22},{"language":"default","tag":"Credit","count":18},{"language":"default","tag":"Data exports","count":16}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"self-serve/trial-management","slug":"/self-serve/trial-management","pageMetadata":{"title":"Trials with prepaid credits","description":null,"href":"/self-serve/trial-management"},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Tip}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`In this example, we’ll set up a 30-day trial that ends when either the time limit expires or the customer runs out of credits, whichever comes first. Customers can upgrade to a paid plan at any time by adding a payment method.`}),`\n`,_jsx(_components.p,{children:`The trial works as follows:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:`Customers receive 1,000 free credits when they sign up. These credits expire after 30 days.`}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:`The trial ends when the customer runs out of credits or when 30 days have elapsed, whichever comes first.`}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:`Customers can use your product while they have available credits. When credits are depleted, access is blocked.`}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:`Customers are not invoiced during the trial. Invoices only occur after they add a payment method and upgrade to the paid plan.`}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:`When a customer adds a payment method, they immediately upgrade to a $20/month Pro plan that includes 20 credits per month. Additional credits can be purchased on-demand or via automatic top-ups.`}),`\n`]}),`\n`]}),`\n`,_jsx(Tip,{children:_jsx(_components.p,{children:`Use separate plans for trial and paid tiers. This provides clear visibility into trial vs paid customers and ensures credits persist through the upgrade process.`})}),`\n`,_jsx(Heading,{level:`2`,id:`core-approach`,children:`Core approach`}),`\n`,_jsx(Heading,{level:`3`,id:`two-plan-model`,children:`Two-plan model`}),`\n`,_jsx(_components.p,{children:`Create two separate plans in Orb:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Trial plan`}),`: No recurring charge, no credit allocation. Acts as a marker for trial customers and defines the trial period (30 days).`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Pro plan`}),`: $20/month recurring charge with a 20-credit monthly allocation. This is the paid tier customers upgrade to.`]}),`\n`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`The trial plan does not include a credit allocation. Instead, you grant credits separately using the ledger entry API. This ensures credits persist when customers upgrade from trial to paid.`}),`\n`,_jsx(Tip,{children:_jsx(_components.p,{children:`Credits granted via plan allocations expire when you change or cancel the subscription. Credits granted via the ledger entry API persist across plan changes and only expire based on their configured expiration date.`})}),`\n`,_jsx(_components.p,{children:`Send usage events as customers consume credits and configure your billable metric to draw down from the prepaid credit balance.`}),`\n`,_jsx(Heading,{level:`2`,id:`prerequisites`,children:`Prerequisites`}),`\n`,_jsx(_components.p,{children:`Before starting a customer on a trial, set up the following:`}),`\n`,_jsx(Heading,{level:`3`,id:`credit-balance-alerts`,children:`Credit balance alerts`}),`\n`,_jsxs(_components.p,{children:[`Create two alerts for the customer using the `,_jsx(_components.a,{href:`/api-reference/alert/create-customer-alert`,children:`create alert API`}),`:`]}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`credit_balance_depleted`})}),`: Fires when the customer’s credit balance reaches 0`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`credit_balance_recovered`})}),`: Fires when credits are added after depletion`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Set the currency of these alerts to match your pricing unit (e.g., `,_jsx(_components.code,{children:`credits`}),`). You’ll use these webhooks to block and unblock product access.`]}),`\n`,_jsx(Heading,{level:`3`,id:`plan-creation`,children:`Plan creation`}),`\n`,_jsx(_components.p,{children:`Create both the trial plan and Pro plan in Orb:`}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`Trial plan configuration:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`No recurring charges`}),`\n`,_jsx(_components.li,{children:`No credit allocations`}),`\n`,_jsx(_components.li,{children:`Set a default subscription duration of 30 days (configure this as the plan’s default term)`}),`\n`,_jsxs(_components.li,{children:[`Set `,_jsx(_components.code,{children:`external_plan_id=trial`}),` for easy reference in your code`]}),`\n`]}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`Pro plan configuration:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`$20 monthly recurring charge (in-advance)`}),`\n`,_jsxs(_components.li,{children:[`20-credit monthly allocation in `,_jsx(_components.code,{children:`credits`}),` currency`]}),`\n`,_jsx(_components.li,{children:`Credits expire at the end of each month (set this on the allocation)`}),`\n`,_jsxs(_components.li,{children:[`Set `,_jsx(_components.code,{children:`external_plan_id=pro`})]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`trial-setup`,children:`Trial setup`}),`\n`,_jsx(Heading,{level:`3`,id:`subscribe-customer-to-trial-plan`,children:`Subscribe customer to trial plan`}),`\n`,_jsx(_components.p,{children:`When a customer signs up, create a subscription to the trial plan:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`7`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscription `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.subscriptions.create(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_customer_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_plan_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"trial\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` start_date`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2025-03-09T00:00:00Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` end_date`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2025-04-08T23:59:59Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# 30 days from start`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` net_terms`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`end_date`}),` to 30 days from the start date. This schedules automatic cancellation if the customer doesn’t upgrade.`]}),`\n`,_jsx(Heading,{level:`3`,id:`grant-trial-credits`,children:`Grant trial credits`}),`\n`,_jsxs(_components.p,{children:[`After creating the subscription, grant credits using the `,_jsx(_components.a,{href:`/api-reference/credit/create-ledger-entry-by-external-id`,children:`create ledger entry`}),` endpoint:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`orb_client.customers.credits.ledger.create_entry_by_external_id(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_customer_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` entry_type`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"increment\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` amount`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1000`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` currency`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"credits\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` per_unit_cost_basis`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"0.00\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Free trial credits`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` expiry_date`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2025-04-08T23:59:59Z\"`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Match trial end date`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`per_unit_cost_basis`}),` to $0.00 for trial credits to avoid charges. Set `,_jsx(_components.code,{children:`expiry_date`}),` to match the trial end date.`]}),`\n`,_jsx(Heading,{level:`2`,id:`handling-credit-depletion`,children:`Handling credit depletion`}),`\n`,_jsx(Heading,{level:`3`,id:`receive-webhook-notification`,children:`Receive webhook notification`}),`\n`,_jsxs(_components.p,{children:[`When the customer depletes their credit balance, Orb sends a `,_jsx(_components.code,{children:`customer.credit_balance_depleted`}),` webhook to your endpoint:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`9`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer.credit_balance_depleted\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"properties\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"customer_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"pricing_unit\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"credits\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`block-product-access`,children:`Block product access`}),`\n`,_jsx(_components.p,{children:`Do not block access based solely on the webhook. Webhook delivery order is not guaranteed. The customer may have purchased credits between depletion and webhook delivery.`}),`\n`,_jsxs(_components.p,{children:[`Instead, query the customer’s current balance using the `,_jsx(_components.a,{href:`/api-reference/credit/fetch-customer-credit-balance`,children:`fetch credit balance`}),` API when you receive the webhook:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`9`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`balance `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.customers.credits.fetch_by_external_id(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_customer_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` currency`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"credits\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` include_all_blocks`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`False`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Only check currently active blocks`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` balance[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"balance\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`==`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Block access in your system`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` block_customer_access(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`If the balance is 0, block access in your application. Update a status field in your database that your product checks before allowing usage.`}),`\n`,_jsx(Heading,{level:`3`,id:`end-trial-early`,children:`End trial early`}),`\n`,_jsx(_components.p,{children:`If the customer has depleted credits and has not added a payment method, end the trial:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`11`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check if customer has payment method`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`customer `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.customers.fetch_by_external_id(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_customer_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` not`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` customer.get(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"payment_provider_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # No payment method, cancel subscription`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.subscriptions.cancel(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` subscription_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscription[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` cancel_option`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"immediate\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` )`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`handling-trial-expiration`,children:`Handling trial expiration`}),`\n`,_jsx(Heading,{level:`3`,id:`30-day-limit-webhook`,children:`30-day limit webhook`}),`\n`,_jsxs(_components.p,{children:[`When 30 days elapse, Orb automatically cancels the subscription (based on the `,_jsx(_components.code,{children:`end_date`}),` you set). You’ll receive a `,_jsx(_components.code,{children:`subscription.ended`}),` webhook:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"subscription.ended\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"subscription\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"sub_...\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"external_customer_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"ended\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`block-access-on-expiration`,children:`Block access on expiration`}),`\n`,_jsx(_components.p,{children:`When you receive this webhook, check if the customer has upgraded to a paid plan:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`15`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`15`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# List customer's active subscriptions`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscriptions `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.subscriptions.list(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_customer_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` status`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"active\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check if customer has an active Pro subscription`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`has_active_paid_sub `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` any`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sub[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"plan\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`][`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"external_plan_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`==`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"pro\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sub `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` subscriptions[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"data\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` not`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` has_active_paid_sub:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Trial expired without upgrade, block access`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` block_customer_access(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`upgrading-to-paid-plan`,children:`Upgrading to paid plan`}),`\n`,_jsxs(_components.p,{children:[`When a customer wants to upgrade, collect payment information using Stripe’s payment method collection flows. See Stripe’s `,_jsx(_components.a,{href:`https://docs.stripe.com/payments/save-and-reuse`,children:`save and reuse payment methods`}),` documentation. Once the payment method is saved as the customer’s default in Stripe, Orb syncs it automatically.`]}),`\n`,_jsx(Heading,{level:`3`,id:`schedule-plan-change`,children:`Schedule plan change`}),`\n`,_jsx(_components.p,{children:`When the customer adds a payment method, upgrade them immediately to the Pro plan:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`6`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`orb_client.subscriptions.schedule_plan_change(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` subscription_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscription[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_plan_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"pro\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` change_option`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"immediate\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` billing_cycle_alignment`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"plan_change_date\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`change_option=immediate`}),` to upgrade right away. Set `,_jsx(_components.code,{children:`billing_cycle_alignment=plan_change_date`}),` to reset the billing cycle to start today and charge the full $20 monthly fee immediately.`]}),`\n`,_jsx(_components.p,{children:`This creates an invoice for $20 and grants the customer their first 20-credit monthly allocation.`}),`\n`,_jsx(Heading,{level:`3`,id:`unblock-product-access`,children:`Unblock product access`}),`\n`,_jsx(_components.p,{children:`After the plan change completes, unblock access:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`6`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Fetch updated subscription`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscription `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.subscriptions.fetch(subscription_id)`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` subscription[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"plan\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`][`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"external_plan_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`==`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"pro\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Customer upgraded, restore access`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` unblock_customer_access(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`credit-persistence`,children:`Credit persistence`}),`\n`,_jsx(_components.p,{children:`Credits granted during the trial persist through the upgrade because you granted them via the ledger entry API, not as a plan allocation. The customer keeps any remaining trial credits plus receives their first 20-credit monthly allocation from the Pro plan.`}),`\n`,_jsx(Heading,{level:`2`,id:`preventing-double-trials`,children:`Preventing double trials`}),`\n`,_jsx(Heading,{level:`3`,id:`check-subscription-history`,children:`Check subscription history`}),`\n`,_jsx(_components.p,{children:`Before creating a trial subscription, verify the customer hasn’t already had a trial:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`14`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`14`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Fetch subscription schedule to see plan history`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`schedule `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` orb_client.subscriptions.fetch_schedule(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` subscription_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscription[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check if customer was ever on trial plan`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`had_trial `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` any`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` phase[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"plan\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`][`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"external_plan_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`==`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"trial\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` phase `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` schedule`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` had_trial:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Customer already had trial, don't create another`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` raise`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4EC9B0`},children:` Exception`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Customer already used trial\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Alternatively, maintain a `,_jsx(_components.code,{children:`had_trial`}),` boolean in your database when you create the first trial subscription.`]}),`\n`,_jsx(Heading,{level:`3`,id:`subscription-continuity`,children:`Subscription continuity`}),`\n`,_jsx(_components.p,{children:`When a customer upgrades from trial to paid, Orb maintains the same subscription resource. The subscription ID remains constant; only the plan changes. This means:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`A customer can only have one subscription lifecycle`}),`\n`,_jsx(_components.li,{children:`Plan changes don’t reset trial eligibility`}),`\n`,_jsx(_components.li,{children:`Subscription history provides a complete audit trail`}),`\n`]}),`\n`,_jsx(_components.p,{children:`To check if a customer ever had a trial, list their subscriptions and examine the plan history via the fetch schedule endpoint.`}),`\n`,_jsx(Heading,{level:`2`,id:`manual-operations`,children:`Manual operations`}),`\n`,_jsx(Heading,{level:`3`,id:`extending-trials`,children:`Extending trials`}),`\n`,_jsxs(_components.p,{children:[`Extend a trial by updating the subscription’s `,_jsx(_components.code,{children:`end_date`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`orb_client.subscriptions.update(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` subscription_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`subscription[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` end_date`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2025-04-15T23:59:59Z\"`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Extend by one week`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`If you also want to extend the credit expiration, create a new ledger entry with updated credits or modify the existing block’s expiration.`}),`\n`,_jsx(Heading,{level:`3`,id:`compensatory-credits`,children:`Compensatory credits`}),`\n`,_jsx(_components.p,{children:`Grant additional credits during the trial without charges:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`9`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`orb_client.customers.credits.ledger.create_entry_by_external_id(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` external_customer_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"customer-18940\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` entry_type`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"increment\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` amount`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`500`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` currency`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"credits\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` per_unit_cost_basis`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"0.00\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` description`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Compensatory credits for service interruption\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` expiry_date`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2025-04-08T23:59:59Z\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`per_unit_cost_basis`}),` to $0.00 to avoid invoicing. Use the `,_jsx(_components.code,{children:`description`}),` field to document the reason for the grant.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Trials with prepaid credits","description":null,"href":"/self-serve/trial-management"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Core approach","slug":"core-approach","depth":2,"children":[{"title":"Two-plan model","slug":"two-plan-model","depth":3,"children":[]}]},{"title":"Prerequisites","slug":"prerequisites","depth":2,"children":[{"title":"Credit balance alerts","slug":"credit-balance-alerts","depth":3,"children":[]},{"title":"Plan creation","slug":"plan-creation","depth":3,"children":[]}]},{"title":"Trial setup","slug":"trial-setup","depth":2,"children":[{"title":"Subscribe customer to trial plan","slug":"subscribe-customer-to-trial-plan","depth":3,"children":[]},{"title":"Grant trial credits","slug":"grant-trial-credits","depth":3,"children":[]}]},{"title":"Handling credit depletion","slug":"handling-credit-depletion","depth":2,"children":[{"title":"Receive webhook notification","slug":"receive-webhook-notification","depth":3,"children":[]},{"title":"Block product access","slug":"block-product-access","depth":3,"children":[]},{"title":"End trial early","slug":"end-trial-early","depth":3,"children":[]}]},{"title":"Handling trial expiration","slug":"handling-trial-expiration","depth":2,"children":[{"title":"30-day limit webhook","slug":"30-day-limit-webhook","depth":3,"children":[]},{"title":"Block access on expiration","slug":"block-access-on-expiration","depth":3,"children":[]}]},{"title":"Upgrading to paid plan","slug":"upgrading-to-paid-plan","depth":2,"children":[{"title":"Schedule plan change","slug":"schedule-plan-change","depth":3,"children":[]},{"title":"Unblock product access","slug":"unblock-product-access","depth":3,"children":[]},{"title":"Credit persistence","slug":"credit-persistence","depth":3,"children":[]}]},{"title":"Preventing double trials","slug":"preventing-double-trials","depth":2,"children":[{"title":"Check subscription history","slug":"check-subscription-history","depth":3,"children":[]},{"title":"Subscription continuity","slug":"subscription-continuity","depth":3,"children":[]}]},{"title":"Manual operations","slug":"manual-operations","depth":2,"children":[{"title":"Extending trials","slug":"extending-trials","depth":3,"children":[]},{"title":"Compensatory credits","slug":"compensatory-credits","depth":3,"children":[]}]}],"codeExamples":{}},"jsLinks":[],"subdomain":"orb-9bba378a","siteName":"Orb","title":"Trials with prepaid credits - Orb","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-12T18:36:35.503Z","originalFileLocation":"self-serve/trial-management.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"application-name\" content=\"Orb\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Trials with prepaid credits - Orb\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Orb\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.withorb.com/self-serve/trial-management\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://orb-9bba378a.mintlify.site/_mintlify/api/og/v2?division=Self-serve+billing\u0026amp;title=Trials+with+prepaid+credits\u0026amp;theme=2186b2a469dd41dc51bb29c5\u0026amp;signature=cccb7e30f5825538ee06b03fa6927daf3a3b4b3f14af4752418d235f256c6065\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Trials with prepaid credits - Orb\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://orb-9bba378a.mintlify.site/_mintlify/api/og/v2?division=Self-serve+billing\u0026amp;title=Trials+with+prepaid+credits\u0026amp;theme=2186b2a469dd41dc51bb29c5\u0026amp;signature=cccb7e30f5825538ee06b03fa6927daf3a3b4b3f14af4752418d235f256c6065\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/orb-9bba378a/hy43bbps97NOnsM5/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Orb\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#15003F\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.withorb.com/self-serve/trial-management\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/self-serve/trial-management.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.withorb.com/#organization\",\"name\":\"Orb\",\"url\":\"https://docs.withorb.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/orb-9bba378a/LPn-ELJYNR-oFxhG/logo/orb-dark.svg?fit=max\u0026auto=format\u0026n=LPn-ELJYNR-oFxhG\u0026q=85\u0026s=9fbf232788a0bfab91e460473924a06f\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.withorb.com#website\",\"name\":\"Orb\",\"url\":\"https://docs.withorb.com\",\"publisher\":{\"@id\":\"https://docs.withorb.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.withorb.com/self-serve/trial-management#webpage\",\"url\":\"https://docs.withorb.com/self-serve/trial-management\",\"name\":\"Trials with prepaid credits\",\"dateModified\":\"2026-11-12T18:36:35.503Z\",\"isPartOf\":{\"@id\":\"https://docs.withorb.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.withorb.com/self-serve/trial-management#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.withorb.com/self-serve/trial-management#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Self-serve billing\",\"item\":\"https://docs.withorb.com/self-serve/agent-pricing\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Trials with prepaid credits\",\"item\":\"https://docs.withorb.com/self-serve/trial-management\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.withorb.com/self-serve/trial-management#article\",\"headline\":\"Trials with prepaid credits\",\"name\":\"Trials with prepaid credits\",\"url\":\"https://docs.withorb.com/self-serve/trial-management\",\"mainEntityOfPage\":{\"@id\":\"https://docs.withorb.com/self-serve/trial-management#webpage\"},\"dateModified\":\"2026-11-12T18:36:35.503Z\",\"publisher\":{\"@id\":\"https://docs.withorb.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.withorb.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Orb\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Orb\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/self-serve/trial-management.md","siteName":"Orb","nav":{"global":{"anchors":[{"anchor":"Changelog","icon":"newspaper","color":{"light":"#15003F","dark":"#F9FAFB"},"href":"https://changelog.withorb.com"},{"anchor":"Status","icon":"signal","color":{"light":"#15003F","dark":"#F9FAFB"},"href":"https://status.withorb.com"},{"anchor":"Blog","icon":"book-open-cover","color":{"light":"#15003F","dark":"#F9FAFB"},"href":"https://www.withorb.com/blog"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/overview"}]},{"tab":"Implementation guides","groups":[{"group":"Tutorials","pages":[{"title":"Send your first usage event","href":"/tutorials/first-usage-event"},{"title":"Make your first billable metric","href":"/tutorials/first-billable-metric"},{"title":"Make your first plan","href":"/tutorials/first-plan"},{"title":"Make your first subscription","href":"/tutorials/first-subscription"},{"title":"Collect payment against your first issued invoice","href":"/tutorials/first-payment"},{"title":"Use the prepurchase ledger with custom credits","href":"/tutorials/first-custom-credits"},{"title":"Use the prepurchase ledger with multiple custom credit types","href":"/tutorials/multiple-custom-credits"},{"title":"Walk through the Orb settings","href":"/tutorials/settings"}]},{"group":"Usage \u0026 cost","pages":[{"title":"Building a usage dashboard","href":"/usage-cost/usage-dashboard"}]},{"group":"Self-serve billing","pages":[{"title":"Pricing an AI agent","href":"/self-serve/agent-pricing"},{"title":"Product access with prepaid credits","description":null,"href":"/self-serve/product-access"},{"title":"Trials with prepaid credits","href":"/self-serve/trial-management"}]},{"group":"Enterprise","pages":[{"title":"Enterprise billing with Orb","description":null,"href":"/enterprise/enterprise-billing"},{"title":"Commitments","href":"/enterprise/commitments"},{"title":"Managing enterprise credits","href":"/enterprise/managing-credits"}]},{"group":"Migration guides","pages":[{"title":"Migrating from Stripe Billing","href":"/migration-guides/stripe-billing"}]}]},{"tab":"API reference","pages":[{"title":"API reference","href":"/api-reference/idempotency"}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/integrations-and-exports/introduction"}]}]},"basePath":"","title":"Trials with prepaid credits - Orb","buildId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","deploymentId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","dynamics":[],"chunks":[]}