Skip to main content
POST
Import External Billing State
Use this Core API when another system already bills the customer and Nozle should provide the plan entitlements without charging them again. Base URL: https://core.nozle.app/api/v1 Auth: secret key with subscription:write when API permissions are enabled. Publishable keys are rejected. Idempotency-Key is required.

Import the subscription

For an Entity subscription, add external_entity_id beside subscription:
The referenced customer, plan, and optional Entity must already exist in the authenticated organization. The period must contain the current time and span exactly one plan interval. Periods use exact timestamp-based, half-open boundaries: current_period_start is inclusive and current_period_end is the first instant of the next period. Non-midnight payment-provider boundaries are preserved exactly—for example, a monthly period from 2026-08-15T10:37:42Z must end at 2026-09-15T10:37:42Z. Weekly, monthly, quarterly, semiannual, and yearly calendar advancement is supported, including month-end and leap-year clamping. Shorter, longer, or otherwise mismatched periods are rejected. The imported boundaries are authoritative for current usage reporting and opening-balance expiry. Independent credit-grant cadences remain independent—for example, monthly credits on an annual plan still reset monthly—and lifetime grants remain non-expiring.

Response

Nozle creates no invoice, checkout, payment-provider customer, or payment request. Externally billed subscriptions are excluded from Nozle invoicing, upgrades, cancellation, dunning, and payment collection. If credit_import_required is true, import every opening Credit System balance before switching usage authority to Nozle. Scheduled plan grants remain paused until that import is complete. For an Entity import, save the external_subscription_id returned in this response. Nozle generates that identifier for the Entity subscription; external_reference remains your source-system audit reference and is not used as the Entity subscription ID.

Dry run and retries

Set dry_run to true to run the same idempotency, Entity ownership, subscription-slot, grant-scope, and period checks as execution without writing subscription state. Retry an uncertain response with the same idempotency key and identical payload. A replay returns the original result. Reusing the key with a different request is rejected.
This endpoint does not transfer billing authority to Nozle. Adopting payment collection later requires a separate explicit migration flow.
Next: Import the opening credit balance.