interface RequestPolicy { /** Per-attempt timeout in milliseconds. */ timeout: number; /** Extra attempts after a failure. 0 (the default) never retries. */ maxRetries: number; /** First retry delay in milliseconds; it doubles each retry, up to 10 seconds. */ retryDelayMs: number; } interface components { schemas: { /** * @example USD * @enum {string} */ Currency: "AED" | "AFN" | "ALL" | "AMD" | "ANG" | "AOA" | "ARS" | "AUD" | "AWG" | "AZN" | "BAM" | "BBD" | "BDT" | "BGN" | "BIF" | "BMD" | "BND" | "BOB" | "BRL" | "BSD" | "BWP" | "BYN" | "BZD" | "CAD" | "CDF" | "CHF" | "CLF" | "CLP" | "CNY" | "COP" | "CRC" | "CVE" | "CZK" | "DJF" | "DKK" | "DOP" | "DZD" | "EGP" | "ETB" | "EUR" | "FJD" | "FKP" | "GBP" | "GEL" | "GHS" | "GIP" | "GMD" | "GNF" | "GTQ" | "GYD" | "HKD" | "HNL" | "HRK" | "HTG" | "HUF" | "IDR" | "ILS" | "INR" | "ISK" | "JMD" | "JPY" | "KES" | "KGS" | "KHR" | "KMF" | "KRW" | "KYD" | "KZT" | "LAK" | "LBP" | "LKR" | "LRD" | "LSL" | "MAD" | "MDL" | "MGA" | "MKD" | "MMK" | "MNT" | "MOP" | "MRO" | "MUR" | "MVR" | "MWK" | "MXN" | "MYR" | "MZN" | "NAD" | "NGN" | "NIO" | "NOK" | "NPR" | "NZD" | "PAB" | "PEN" | "PGK" | "PHP" | "PKR" | "PLN" | "PYG" | "QAR" | "RON" | "RSD" | "RUB" | "RWF" | "SAR" | "SBD" | "SCR" | "SEK" | "SGD" | "SHP" | "SLL" | "SOS" | "SRD" | "STD" | "SZL" | "THB" | "TJS" | "TOP" | "TRY" | "TTD" | "TWD" | "TZS" | "UAH" | "UGX" | "USD" | "UYU" | "UZS" | "VND" | "VUV" | "WST" | "XAF" | "XCD" | "XOF" | "XPF" | "YER" | "ZAR" | "ZMW"; /** * @example US * @enum {string} */ Country: "AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AO" | "AQ" | "AR" | "AS" | "AT" | "AU" | "AW" | "AX" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BL" | "BM" | "BN" | "BO" | "BQ" | "BR" | "BS" | "BT" | "BV" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CV" | "CW" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GG" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GS" | "GT" | "GU" | "GW" | "GY" | "HK" | "HM" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IM" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JE" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MF" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PN" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "SS" | "ST" | "SV" | "SX" | "SY" | "SZ" | "TC" | "TD" | "TF" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "UM" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "YE" | "YT" | "ZA" | "ZM" | "ZW"; /** * @example America/Los_Angeles * @enum {string} */ Timezone: "UTC" | "Africa/Algiers" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Monrovia" | "Africa/Nairobi" | "America/Argentina/Buenos_Aires" | "America/Bogota" | "America/Caracas" | "America/Chicago" | "America/Chihuahua" | "America/Denver" | "America/Guatemala" | "America/Guyana" | "America/Halifax" | "America/Indiana/Indianapolis" | "America/Juneau" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Mazatlan" | "America/Mexico_City" | "America/Monterrey" | "America/Montevideo" | "America/New_York" | "America/Nuuk" | "America/Phoenix" | "America/Puerto_Rico" | "America/Regina" | "America/Santiago" | "America/Sao_Paulo" | "America/St_Johns" | "America/Tijuana" | "Asia/Almaty" | "Asia/Baghdad" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Chongqing" | "Asia/Colombo" | "Asia/Dhaka" | "Asia/Hong_Kong" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Kathmandu" | "Asia/Kolkata" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuwait" | "Asia/Magadan" | "Asia/Muscat" | "Asia/Novosibirsk" | "Asia/Riyadh" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Tokyo" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yangon" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Cape_Verde" | "Atlantic/South_Georgia" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Darwin" | "Australia/Hobart" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Europe/Amsterdam" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Helsinki" | "Europe/Istanbul" | "Europe/Kaliningrad" | "Europe/Kyiv" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Madrid" | "Europe/Minsk" | "Europe/Moscow" | "Europe/Paris" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/Sarajevo" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zurich" | "GMT+12" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Chatham" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Majuro" | "Pacific/Midway" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Port_Moresby" | "Pacific/Tongatapu"; /** @description Billing entity object */ BillingEntityObject: { /** * Format: uuid * @description A unique identifier for the billing entity in the Nozle application * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The unique code of the billing entity * @example acme_corp */ code: string; /** * @description The name of the billing entity * @example Acme Corp */ name: string; /** * @description The default currency of the billing entity * @example USD */ default_currency: components["schemas"]["Currency"]; /** * @description The language of the documents generated for this billing entity * @example en */ document_locale: string; /** * @description The type of document numbering for this billing entity: * - `per_customer`: document numbers are unique per customer * - `per_billing_entity`: document numbers are unique per billing entity * @example per_customer * @enum {string} */ document_numbering: "per_customer" | "per_billing_entity"; /** * @description The prefix used in document numbers for this billing entity * @example ABC-123 */ document_number_prefix?: string | null; /** * @description Whether to finalize invoices with zero amount for this billing entity * @example true */ finalize_zero_amount_invoice: boolean; /** * @description The footer text to be displayed on invoices for this billing entity * @example Thank you for your business */ invoice_footer?: string | null; /** * @description The grace period (in days) for invoice finalization * @example 0 */ invoice_grace_period: number; /** * @description Defines whether the issuing date follows the current billing period's end date or the next period starting date. * @default next_period_start * @enum {string} */ subscription_invoice_issuing_date_anchor: "current_period_end" | "next_period_start"; /** * @description The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period. * @default align_with_finalization_date * @enum {string} */ subscription_invoice_issuing_date_adjustment: "align_with_finalization_date" | "keep_anchor"; /** * @description Whether this billing entity is the default billing entity for the organization. Default billing entity will be used as fallback in services if no billing entity is specified when billing_entity is not provided. Default billing entity is the billing entity that will be used to generate invoices if no billing entity is specified when invoice is created. is the oldest active billing entity and this flag cannot be changed * @example false */ is_default?: boolean; /** * @description The net payment term (in days) for this billing entity * @example 0 */ net_payment_term: number; /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string | null; /** * @description The second line of the billing address * @example Suite 100 */ address_line2?: string | null; /** * @description The city of the billing address * @example Woodland Hills */ city?: string | null; /** * @description The state of the billing address * @example CA */ state?: string | null; /** @description The country code of the billing address */ country?: components["schemas"]["Country"]; /** * @description The zipcode of the billing address * @example 91364 */ zipcode?: string | null; /** * Format: email * @description The email address of the billing entity * @example billing@acme.com */ email?: string | null; /** * @description The legal name of the billing entity * @example Acme Corporation */ legal_name?: string | null; /** * @description The legal registration number of the billing entity * @example US123456789 */ legal_number?: string | null; /** * @description The tax identification number of the billing entity * @example EU123456789 */ tax_identification_number?: string | null; /** * @description The timezone of the billing entity * @example UTC */ timezone: components["schemas"]["Timezone"]; /** @description The email notification settings for this billing entity. `subscription.price_change_scheduled` is off until you add it; it emails a customer when a plan version migration moves their subscription to a different price. */ email_settings?: ("invoice.finalized" | "credit_note.created" | "payment_receipt.created" | "subscription.price_change_scheduled" | "dunning.step")[]; /** * @description Whether EU tax management is enabled for this billing entity * @example false */ eu_tax_management?: boolean; /** * Format: uri * @description The URL of the billing entity's logo * @example https://app.example.com/logo.png */ logo_url?: string | null; /** * Format: date-time * @description The date and time when the billing entity was created * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description The date and time when the billing entity was last updated * @example 2022-04-29T08:59:51Z */ updated_at: string; }; ApiErrorUnauthorized: { /** * Format: int32 * @example 401 */ status: number; /** @example Unauthorized */ error: string; }; ApiErrorUnprocessableEntity: { /** * Format: int32 * @example 422 */ status: number; /** @example Unprocessable entity */ error: string; /** @example validation_errors */ code: string; error_details: Record; }; /** @description Billing entity create input */ BillingEntityCreateInput: { billing_entity: { /** * @description The unique code of the billing entity * @example acme_corp */ code: string; /** * @description The name of the billing entity * @example Acme Corp */ name: string; /** * @description The default currency of the billing entity * @example USD */ default_currency?: components["schemas"]["Currency"]; /** * @description The type of document numbering for this billing entity: * - `per_customer`: document numbers are unique per customer * - `per_billing_entity`: document numbers are unique per billing entity * @enum {string} */ document_numbering?: "per_customer" | "per_billing_entity"; /** * @description The prefix used in document numbers for this billing entity * @example ABC-123 */ document_number_prefix?: string | null; /** * @description Whether to finalize invoices with zero amount for this billing entity * @example true */ finalize_zero_amount_invoice?: boolean; billing_configuration?: { /** * @description The footer text to be displayed on invoices for this billing entity * @example Thank you for your business */ invoice_footer?: string; /** * @description The language of the documents generated for this billing entity * @example en */ document_locale?: string; /** * @description The grace period (in days) for invoice finalization * @example 0 */ invoice_grace_period?: number; /** * @description Defines whether the issuing date follows the current billing period's end date or the next period starting date. * @default next_period_start * @enum {string} */ subscription_invoice_issuing_date_anchor: "current_period_end" | "next_period_start"; /** * @description The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period. * @default align_with_finalization_date * @enum {string} */ subscription_invoice_issuing_date_adjustment: "align_with_finalization_date" | "keep_anchor"; }; /** * @description The net payment term (in days) for this billing entity * @example 0 */ net_payment_term?: number; /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string | null; /** * @description The second line of the billing address * @example Suite 100 */ address_line2?: string | null; /** * @description The city of the billing address * @example Woodland Hills */ city?: string | null; /** * @description The state of the billing address * @example CA */ state?: string | null; /** @description The country code of the billing address */ country?: components["schemas"]["Country"]; /** * @description The zipcode of the billing address * @example 91364 */ zipcode?: string | null; /** * Format: email * @description The email address of the billing entity * @example billing@acme.com */ email?: string | null; /** * @description The legal name of the billing entity * @example Acme Corporation */ legal_name?: string | null; /** * @description The legal registration number of the billing entity * @example US123456789 */ legal_number?: string | null; /** * @description The tax identification number of the billing entity * @example EU123456789 */ tax_identification_number?: string | null; /** * @description The timezone of the billing entity * @example UTC */ timezone?: components["schemas"]["Timezone"]; /** @description The email notification settings for this billing entity. `subscription.price_change_scheduled` is off until you add it. */ email_settings?: ("invoice.finalized" | "credit_note.created" | "subscription.price_change_scheduled" | "dunning.step")[]; /** * @description Whether EU tax management is enabled for this billing entity * @example false */ eu_tax_management?: boolean; /** * Format: uri * @description The base64 encoded logo image for the billing entity * @example data:image/png;base64,... */ logo?: string | null; }; }; ApiErrorBadRequest: { /** * Format: int32 * @example 400 */ status: number; /** @example Bad request */ error: string; }; ApiErrorForbidden: { /** * Format: int32 * @example 403 */ status: number; /** @example Forbidden */ error: string; /** @example feature_unavailable */ code: string; }; TaxObject: { /** * Format: uuid * @description Unique identifier of the tax, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Name of the tax. * @example TVA */ name: string; /** * @description Unique code used to identify the tax associated with the API request. * @example french_standard_vat */ code: string; /** * @description Internal description of the tax * @example French standard VAT */ description?: string | null; /** * @description The percentage rate of the tax * @example 20 */ rate: number; /** * @deprecated * @description This field is deprecated and will be removed in a future version. When set to true, it applies the tax to the organization's default billing entity. To apply or remove a tax from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead. * @example true */ applied_to_organization: boolean; /** * @description Reserved. Always `0`. Do not rely on it. * @example 0 * @enum {integer} */ add_ons_count?: 0; /** * @description Reserved. Always `0`. Do not rely on it. * @example 0 * @enum {integer} */ customers_count?: 0; /** * @description Reserved. Always `0`. Do not rely on it. * @example 0 * @enum {integer} */ plans_count?: 0; /** * @description Reserved. Always `0`. Do not rely on it. * @example 0 * @enum {integer} */ charges_count?: 0; /** * @description Reserved. Always `0`. Do not rely on it. * @example 0 * @enum {integer} */ commitments_count?: 0; /** * Format: date-time * @description Creation date of the tax. * @example 2023-07-06T14:35:58Z */ created_at: string; }; InvoiceCustomSectionObject: { /** * Format: uuid * @description Unique identifier for the invoice custom section in the Nozle application, generated by Nozle to ensure record uniqueness within the system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Name of the invoice custom section. * @example EU Bank Details */ name: string; /** * @description Unique code identifying the invoice custom section for the API request. * @example eu_bank_details */ code: string; /** * @description Internal description of the invoice custom section. * @example This section contains the bank details for EU customers. */ description?: string; /** * @description The value shown on the invoice PDF. * @example Bank Name: Nozle Bank, IBAN: FR7630004000031234567890143 */ details?: string; /** * @description The name of the invoice custom section displayed on the invoice. * @example Bank Details: */ display_name?: string; /** * @deprecated * @description This field is deprecated and will be removed in a future version. When set to true, it applies the invoice custom section to the organization's default billing entity. To apply or remove an invoice custom section from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead. * @example true */ applied_to_organization?: boolean; /** * Format: uuid * @description Unique identifier for the organization associated with the invoice custom section. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id?: string; /** * Format: date-time * @description Creation date of the tax. * @example 2023-07-06T14:35:58Z */ created_at?: string; }; BillingEntityObjectExtended: components["schemas"]["BillingEntityObject"] & { taxes?: components["schemas"]["TaxObject"][]; selected_invoice_custom_sections?: components["schemas"]["InvoiceCustomSectionObject"][]; }; ApiErrorNotFound: { /** * Format: int32 * @example 404 */ status: number; /** @example Not Found */ error: string; /** @example object_not_found */ code: string; }; /** * @description List of unique code used to identify the taxes. * @example [ * "french_standard_vat" * ] */ TaxCodes: string[]; /** @description Billing entity update input */ BillingEntityUpdateInput: { /** * @description The name of the billing entity * @example Acme Corp */ name?: string; /** * @description The default currency of the billing entity * @example USD */ default_currency?: components["schemas"]["Currency"]; /** * @description The type of document numbering for this billing entity: * - `per_customer`: document numbers are unique per customer * - `per_billing_entity`: document numbers are unique per billing entity * @enum {string} */ document_numbering?: "per_customer" | "per_billing_entity"; /** * @description The prefix used in document numbers for this billing entity * @example ABC-123 */ document_number_prefix?: string | null; /** * @description Whether to finalize invoices with zero amount for this billing entity * @example true */ finalize_zero_amount_invoice?: boolean; billing_configuration?: { /** * @description The footer text to be displayed on invoices for this billing entity * @example Thank you for your business */ invoice_footer?: string; /** * @description The language of the documents generated for this billing entity * @example en */ document_locale?: string; /** * @description The grace period (in days) for invoice finalization * @example 0 */ invoice_grace_period?: number; /** * @description Defines whether the issuing date follows the current billing period's end date or the next period starting date. * @default next_period_start * @enum {string} */ subscription_invoice_issuing_date_anchor: "current_period_end" | "next_period_start"; /** * @description The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period. * @default align_with_finalization_date * @enum {string} */ subscription_invoice_issuing_date_adjustment: "align_with_finalization_date" | "keep_anchor"; }; /** * @description The net payment term (in days) for this billing entity * @example 0 */ net_payment_term?: number; /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string | null; /** * @description The second line of the billing address * @example Suite 100 */ address_line2?: string | null; /** * @description The city of the billing address * @example Woodland Hills */ city?: string | null; /** * @description The state of the billing address * @example CA */ state?: string | null; /** @description The country code of the billing address */ country?: components["schemas"]["Country"]; /** * @description The zipcode of the billing address * @example 91364 */ zipcode?: string | null; /** * Format: email * @description The email address of the billing entity * @example billing@acme.com */ email?: string | null; /** * @description The legal name of the billing entity * @example Acme Corporation */ legal_name?: string | null; /** * @description The legal registration number of the billing entity * @example US123456789 */ legal_number?: string | null; /** * @description The tax identification number of the billing entity * @example EU123456789 */ tax_identification_number?: string | null; /** * @description The timezone of the billing entity * @example UTC */ timezone?: components["schemas"]["Timezone"]; /** @description The tax codes that should be associated with this billing entity */ tax_codes?: components["schemas"]["TaxCodes"]; /** @description The email notification settings for this billing entity. `subscription.price_change_scheduled` is off until you add it. */ email_settings?: ("invoice.finalized" | "credit_note.created" | "subscription.price_change_scheduled" | "dunning.step")[]; /** * @description Whether EU tax management is enabled for this billing entity * @example false */ eu_tax_management?: boolean; /** * Format: uri * @description The base64 encoded logo image for the billing entity. Sending "null" will remove the logo, if any exist. * @example data:image/png;base64,... */ logo?: string | null; /** * @description The codes of the invoice custom section that should be associated with this billing entity * @example [ * "custom_section_1", * "custom_section_2" * ] */ invoice_custom_section_codes?: string[]; }; ActivityLogObject: { /** * Format: uuid * @description Unique identifier assigned to the activity log within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the activity log record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ activity_id: string; /** * Format: email * @description The email of the user who performed the activity * @example dinesh@piedpiper.test */ user_email?: string | null; /** * @description This field stores the actitivy action that was performed to the activity_object. * @example billing_metric.created */ activity_type: string; /** * @description This field represents the source of the activity log, the interaction source that triggered the action. * @example api * @enum {string} */ activity_source: "api" | "front" | "system"; /** * Format: object * @description This field represents the final state of the object that the action was applied. * @example { * "nozle_id": "dad68bc7-c01a-4ad8-a87b-13e78693a5bc", * "plan_id": "b9155544-e261-4e92-b54e-f65d7609294c" * } */ activity_object?: Record | null; /** * Format: object * @example { * "plan_id": [ * null, * "b9155544-e261-4e92-b54e-f65d7609294c" * ] * } */ activity_object_changes?: Record | null; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id?: string | null; /** * @description Unique identifier assigned to the subscription in your application. * @example external_id */ external_subscription_id?: string | null; /** * Format: uuid * @description The resource id of the object that the action was applied. * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ resource_id: string; /** * @description The resource type of the resource_id record. * @example Feature */ resource_type: string; /** * Format: uuid * @description Unique identifier for the organization associated with the activity log. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * Format: date-time * @description The logged date of the activity, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Nozle application * @example 2025-03-31T12:31:44Z */ logged_at: string; /** * Format: date-time * @description The creation date of the activity record in the Nozle application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Nozle application * @example 2022-04-29T08:59:51Z */ created_at: string; }; PaginationMeta: { /** * @description Current page. * @example 2 */ current_page: number; /** * @description Next page. * @example 3 */ next_page?: number | null; /** * @description Previous page. * @example 1 */ prev_page?: number | null; /** * @description Total number of pages. * @example 4 */ total_pages: number; /** * @description Total number of records. * @example 70 */ total_count: number; }; ActivityLogsPaginated: { activity_logs: components["schemas"]["ActivityLogObject"][]; meta: components["schemas"]["PaginationMeta"]; }; ActivityLog: { activity_log: components["schemas"]["ActivityLogObject"]; }; AddOnObject: { /** * Format: uuid * @description Unique identifier of the add-on, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The name of the add-on. * @example Setup Fee */ name: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup Fee (SF1) */ invoice_display_name: string | null; /** * @description Unique code used to identify the add-on. * @example setup_fee */ code: string; /** * @description The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value. * @example 50000 */ amount_cents: number; /** * @description The currency of the add-on. * @example USD */ amount_currency: components["schemas"]["Currency"]; /** * @description The description of the add-on. * @example Implementation fee for new customers. */ description: string | null; /** * Format: date-time * @description The date and time when the add-on was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the add-on was initially created. * @example 2022-04-29T08:59:51Z */ created_at: string; /** @description All taxes applied to the add-on. */ taxes?: components["schemas"]["TaxObject"][]; }; AddOnsPaginated: { add_ons: components["schemas"]["AddOnObject"][]; meta: components["schemas"]["PaginationMeta"]; }; AddOnBaseInput: { /** * @description The name of the add-on. * @example Setup Fee */ name?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup Fee (SF1) */ invoice_display_name?: string | null; /** * @description Unique code used to identify the add-on. * @example setup_fee */ code?: string; /** * @description The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value. * @example 50000 */ amount_cents?: number; /** * @description The currency of the add-on. * @example USD */ amount_currency?: components["schemas"]["Currency"]; /** * @description The description of the add-on. * @example Implementation fee for new customers. */ description?: string | null; tax_codes?: components["schemas"]["TaxCodes"]; }; AddOnCreateInput: { add_on: components["schemas"]["AddOnBaseInput"]; }; AddOn: { add_on: components["schemas"]["AddOnObject"]; }; AddOnUpdateInput: { add_on: components["schemas"]["AddOnBaseInput"]; }; ApiLogObject: { /** * @description Nozle API version used in the request. * @example v1 */ api_version: string; /** * @description The client used to make the request to the API. * @example Nozle Ruby v1.26.0 */ client: string; /** * @description This field represents the HTTP method of the request. * @example post * @enum {string} */ http_method: "post" | "put" | "delete"; /** * @description This field represents the HTTP status of the requests. * @example 200 */ http_status: number; /** * Format: date-time * @description The logged date of the api log, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Nozle application * @example 2025-03-31T12:31:44Z */ logged_at: string; /** * Format: object * @example { "feature": { "name": "Storage", "code": "storage" } } */ request_body: string; /** * @description This field represents the API origin of the requested URL * @example https://app.nozle.app/ */ request_origin: string; /** * @description This field represents the API path of the requested URL * @example /features */ request_path: string; /** * Format: date-time * @description The creation date of the api log record in the Nozle application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Nozle application * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: uuid * @description Unique identifier for the api log. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ request_id: string; /** * Format: object * @example { "nozle_id": "b9155544-e261-4e92-b54e-f65d7609294c", ... } */ request_response?: string; }; ApiLogsPaginated: { api_logs: components["schemas"]["ApiLogObject"][]; meta: components["schemas"]["PaginationMeta"]; }; ApiLog: { api_log: components["schemas"]["ApiLogObject"]; }; GrossRevenueObject: { /** * @description Identifies the month to analyze revenue. * @example 2023-11-01T00:00:00.000Z */ month: string; /** * @description The total amount of revenue for a period, expressed in cents. * @example 50000 */ amount_cents: number; /** * @description The currency of revenue analytics. Format must be ISO 4217. * @example USD */ currency: components["schemas"]["Currency"]; /** * @description Contains invoices count. * @example 10 */ invoices_count: number; }; GrossRevenues: { gross_revenues: components["schemas"]["GrossRevenueObject"][]; }; InvoiceCollectionObject: { /** * @description Identifies the month to analyze revenue. * @example 2023-11-01T00:00:00.000Z */ month: string; /** * @description The payment status of the invoices. * @example succeeded * @enum {string} */ payment_status?: "pending" | "succeeded" | "failed"; /** * @description Contains invoices count. * @example 10 */ invoices_count: number; /** * @description The total amount of revenue for a period, expressed in cents. * @example 50000 */ amount_cents?: number; /** * @description The currency of revenue analytics. Format must be ISO 4217. * @example USD */ currency?: components["schemas"]["Currency"]; }; InvoiceCollections: { invoice_collections: components["schemas"]["InvoiceCollectionObject"][]; }; InvoicedUsageObject: { /** * @description Identifies the month to analyze revenue. * @example 2023-11-01T00:00:00.000Z */ month: string; /** * @description The code of the usage-based features. * @example code1 */ code?: string; /** * @description The total amount of revenue for a period, expressed in cents. * @example 50000 */ amount_cents: number; /** * @description The currency of revenue analytics. Format must be ISO 4217. * @example USD */ currency: components["schemas"]["Currency"]; }; InvoicedUsages: { invoiced_usages: components["schemas"]["InvoicedUsageObject"][]; }; MrrObject: { /** * @description Identifies the month to analyze MRR. * @example 2023-11-01T00:00:00.000Z */ month: string; /** * @description The total amount of MRR, expressed in cents. * @example 50000 */ amount_cents: number; /** * @description The currency of MRR analytics. Format must be ISO 4217. * @example USD */ currency: components["schemas"]["Currency"]; }; Mrrs: { mrrs: components["schemas"]["MrrObject"][]; }; OverdueBalanceObject: { /** * @description Identifies the month to analyze revenue. * @example 2023-11-01T00:00:00.000Z */ month: string; /** * @description The total amount of revenue for a period, expressed in cents. * @example 50000 */ amount_cents: number; /** * @description The currency of revenue analytics. Format must be ISO 4217. * @example USD */ currency: components["schemas"]["Currency"]; /** * @description The Nozle invoice IDs associated with the revenue. * @example [ * "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" * ] */ invoice_ids: string[]; }; OverdueBalances: { overdue_balances: components["schemas"]["OverdueBalanceObject"][]; }; UsageObject: { /** * Format: uuid * @description The unique identifier of the organization for which the usage analytics is calculated. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * Format: date * @description The start date of the period for which the usage analytics is calculated. * @example 2023-11-01 */ start_of_period_dt?: string; /** * Format: date * @description The end date of the period for which the usage analytics is calculated. * @example 2023-11-30 */ end_of_period_dt?: string; /** * @description The currency of usage analytics. Format must be ISO 4217. * @example USD */ amount_currency: components["schemas"]["Currency"]; /** * @description The total amount for usages for a period, expressed in cents. * @example 50000 */ amount_cents: number; /** * @description The code of the usage-based features. * @example code1 */ feature_code?: string; /** * @description The total number of units for the usage-based features. * @example 1.0 */ units?: string; /** * @description Indicates whether the feature associated with the usage is deleted. * @example false */ is_feature_deleted?: boolean; }; Usages: { usages: components["schemas"]["UsageObject"][]; }; /** * @example USD * @enum {string|null} */ CurrencyOrNull: null | "AED" | "AFN" | "ALL" | "AMD" | "ANG" | "AOA" | "ARS" | "AUD" | "AWG" | "AZN" | "BAM" | "BBD" | "BDT" | "BGN" | "BIF" | "BMD" | "BND" | "BOB" | "BRL" | "BSD" | "BWP" | "BYN" | "BZD" | "CAD" | "CDF" | "CHF" | "CLF" | "CLP" | "CNY" | "COP" | "CRC" | "CVE" | "CZK" | "DJF" | "DKK" | "DOP" | "DZD" | "EGP" | "ETB" | "EUR" | "FJD" | "FKP" | "GBP" | "GEL" | "GIP" | "GMD" | "GNF" | "GTQ" | "GYD" | "HKD" | "HNL" | "HRK" | "HTG" | "HUF" | "IDR" | "ILS" | "INR" | "ISK" | "JMD" | "JPY" | "KES" | "KGS" | "KHR" | "KMF" | "KRW" | "KYD" | "KZT" | "LAK" | "LBP" | "LKR" | "LRD" | "LSL" | "MAD" | "MDL" | "MGA" | "MKD" | "MMK" | "MNT" | "MOP" | "MRO" | "MUR" | "MVR" | "MWK" | "MXN" | "MYR" | "MZN" | "NAD" | "NGN" | "NIO" | "NOK" | "NPR" | "NZD" | "PAB" | "PEN" | "PGK" | "PHP" | "PKR" | "PLN" | "PYG" | "QAR" | "RON" | "RSD" | "RUB" | "RWF" | "SAR" | "SBD" | "SCR" | "SEK" | "SGD" | "SHP" | "SLL" | "SOS" | "SRD" | "STD" | "SZL" | "THB" | "TJS" | "TOP" | "TRY" | "TTD" | "TWD" | "TZS" | "UAH" | "UGX" | "USD" | "UYU" | "UZS" | "VND" | "VUV" | "WST" | "XAF" | "XCD" | "XOF" | "XPF" | "YER" | "ZAR" | "ZMW"; AppliedCouponObject: { /** * Format: uuid * @description Unique identifier of the applied coupon, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the coupon, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ coupon_id: string; /** * @description Unique code used to identify the coupon. * @example startup_deal */ coupon_code: string; /** * @description The name of the coupon. * @example Startup Deal */ coupon_name: string; /** * @description The status of the parent coupon. Can be either `active` or `terminated`. * @example active * @enum {string} */ coupon_status?: "active" | "terminated"; /** * Format: date-time * @description The date and time when the parent coupon was deleted. If null, the coupon still exists. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2022-04-29T08:59:51Z */ coupon_deleted_at?: string | null; /** * Format: uuid * @description Unique identifier of the customer, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The status of the coupon. Can be either `active` or `terminated`. * @example active * @enum {string} */ status: "active" | "terminated"; /** * @description The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. * @example 2000 */ amount_cents?: number | null; /** * @description The remaining amount in cents for a `fixed_amount` coupon with a frequency set to `once`. This field indicates the remaining balance or value that can still be utilized from the coupon. * @example 50 */ amount_cents_remaining?: number | null; /** * @description The currency of the coupon. This field is required only for coupon with `fixed_amount` type. * @example EUR */ amount_currency?: components["schemas"]["CurrencyOrNull"]; /** * @description The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. * @example null */ percentage_rate?: string | null; /** * @description The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`. * * - If set to `once`, the coupon is applicable only for a single use. * - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. * - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely. * @example recurring * @enum {string} */ frequency: "once" | "recurring" | "forever"; /** * @description Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type * @example 3 */ frequency_duration?: number | null; /** * @description The remaining number of billing periods to which the coupon is applicable. This field determines the remaining usage or availability of the coupon based on the remaining billing periods. * @example 1 */ frequency_duration_remaining?: number | null; /** * Format: date-time * @description The date and time after which the coupon will stop applying to customer's invoices. Once the expiration date is reached, the coupon will no longer be applicable, and any further invoices generated for the customer will not include the coupon discount. * @example 2022-04-29T08:59:51Z */ expiration_at?: string | null; /** * Format: date-time * @description The date and time when the coupon was assigned to a customer. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description This field indicates the specific moment when the coupon amount is fully utilized or when the coupon is removed from the customer's coupon list. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2022-04-29T08:59:51Z */ terminated_at?: string | null; }; CreditObject: { /** * Format: uuid * @description Unique identifier assigned to the credit within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the credit's item record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The amount of credit associated with the invoice, expressed in cents. * @example 1200 */ amount_cents: number; /** * @description The currency of the credit. * @example EUR */ amount_currency: components["schemas"]["Currency"]; /** * @description Indicates whether the credit is applied on the amount before taxes (coupons) or after taxes (credit notes). This flag helps determine the order in which credits are applied to the invoice calculation * @example false */ before_taxes: boolean; /** @description The item attached to the credit. */ item: { /** * Format: uuid * @description Unique identifier assigned to the credit item within the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ item_id: string; /** * @description The type of credit applied. Possible values are `coupon`, `credit_note` or `invoice` (for `progressive_billing` invoice). * @example coupon * @enum {string} */ type: "coupon" | "credit_note" | "invoice"; /** * @description The code of the credit applied. It can be the code of the coupon attached to the credit, the credit note's number or the `progressive_billing` invoice number. * @example startup_deal */ code: string; /** * @description The name of the credit applied. It can be the name of the coupon attached to the credit, the initial invoice's number linked to the credit note or the `progressive_billing` invoice number. * @example Startup Deal */ name: string; }; invoice: { /** * Format: uuid * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @example succeeded * @enum {string} */ payment_status: "pending" | "succeeded" | "failed"; }; }; AppliedCouponObjectExtended: components["schemas"]["AppliedCouponObject"] & { credits: components["schemas"]["CreditObject"][]; }; AppliedCouponsPaginated: { applied_coupons: components["schemas"]["AppliedCouponObjectExtended"][]; meta: components["schemas"]["PaginationMeta"]; }; AppliedCouponInput: { applied_coupon: { /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description Unique code used to identify the coupon. * @example startup_deal */ coupon_code: string; /** * @description The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`. * * - If set to `once`, the coupon is applicable only for a single use. * - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. * - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely. * @example recurring * @enum {string|null} */ frequency?: "once" | "recurring" | "forever" | null; /** * @description Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type * @example 3 */ frequency_duration?: number | null; /** * @description The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. * @example 2000 */ amount_cents?: number | null; /** * @description The currency of the coupon. This field is required only for coupon with `fixed_amount` type. * @example EUR */ amount_currency?: components["schemas"]["CurrencyOrNull"]; /** * @description The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. * @example null */ percentage_rate?: string | null; }; }; AppliedCoupon: { applied_coupon: components["schemas"]["AppliedCouponObject"]; }; /** @description Values used to segment metered Feature events. */ FeatureFilterObject: { /** @example region */ key: string; /** * @example [ * "us-east-1" * ] */ values: string[]; }; FeatureFilterInput: { /** @example region */ key: string; /** * @example [ * "us-east-1" * ] */ values: string[]; }; FeaturePrivilegeObject: { /** * @description Unique code for the privilege. * @example max */ code: string; /** * @description Display name for the privilege. * @example Maximum */ name: string | null; /** * @description Data type of the privilege value. Default: string * @example integer * @enum {string} */ value_type: "integer" | "boolean" | "string" | "select"; config: { /** * @description Array of string, required only when value_type is `select`. * @example [ * "google", * "microsoft" * ] */ select_options?: string[]; }; }; FeatureObject: { /** * Format: uuid * @description Unique identifier of the Feature created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Immutable code used for entitlement checks and metered events. * @example seats */ code: string; /** * @description Name of the feature. Max 255 characters. * @example Number of seats */ name: string; /** * @description Description of the feature. Max 600 characters. * @example Number of users of the account */ description?: string | null; /** * @description Determines which Feature configuration is active. Immutable after creation. * @example metered * @enum {string} */ feature_type: "boolean" | "config" | "metered"; /** * @description Privileges for boolean and config Features. Config Features require at least one. * @example [ * { * "code": "max", * "name": "Maximum", * "value_type": "integer", * "config": {} * }, * { * "code": "max_admins", * "name": "Max Admins", * "value_type": "integer", * "config": {} * }, * { * "code": "root", * "name": "Allow root user", * "value_type": "boolean", * "config": {} * }, * { * "code": "provider", * "name": "SSO Provider", * "value_type": "select", * "config": { * "select_options": [ * "google", * "microsoft" * ] * } * } * ] */ privileges?: components["schemas"]["FeaturePrivilegeObject"][]; /** * @description Aggregation method for a metered Feature. * @example sum_agg * @enum {string|null} */ aggregation_type?: "count_agg" | "sum_agg" | "max_agg" | "unique_count_agg" | "weighted_sum_agg" | "latest_agg" | "custom_agg" | null; /** * @description Whether metered usage consumes an allowance or Credit System balance. * @example true */ consumable?: boolean | null; /** * @description Whether accumulated usage carries into the next billing period. * @example false */ recurring?: boolean | null; /** * @description Event property aggregated by the metered Feature. * @example tokens */ field_name?: string | null; /** @example round((ended_at - started_at) * units) */ expression?: string | null; /** @description Custom aggregation implementation when aggregation_type is custom_agg. */ custom_aggregator?: string | null; /** @enum {string|null} */ weighted_interval?: "seconds" | null; /** @enum {string|null} */ rounding_function?: "ceil" | "floor" | "round" | null; /** @example 2 */ rounding_precision?: number | null; filters?: components["schemas"]["FeatureFilterObject"][]; /** * Format: date-time * @description Creation date of the feature. * @example 2025-07-17T12:34:35Z */ created_at: string; }; FeaturesPaginated: { features: components["schemas"]["FeatureObject"][]; meta: components["schemas"]["PaginationMeta"]; }; FeatureBaseInput: { /** * @description Immutable Feature behavior selected at creation. * @enum {string} */ feature_type?: "boolean" | "config" | "metered"; /** * @description Name of the feature. * @example Number of seats */ name?: string | null; /** * @description Internal description of the feature. * @example Number of users of the account */ description?: string | null; /** * @description Privileges associated with this feature. Can be empty. * @example [ * { * "code": "max", * "name": "Maximum", * "value_type": "integer" * }, * { * "code": "max_admins", * "name": "Max Admins", * "value_type": "integer" * }, * { * "code": "root", * "name": "Allow root user", * "value_type": "boolean" * }, * { * "code": "provider", * "name": "SSO Provider", * "value_type": "select", * "config": { * "select_options": [ * "google", * "microsoft" * ] * } * } * ] */ privileges?: { /** * @description Unique code for the privilege. * @example max */ code: string; /** * @description Display name for the privilege. * @example Maximum */ name?: string | null; /** * @description Data type of the privilege value. Default: string * @example integer * @enum {string} */ value_type?: "integer" | "boolean" | "string" | "select"; config?: { /** * @description Array of string, required only when value_type is `select`. * @example [ * "google", * "microsoft" * ] */ select_options?: string[]; }; }[]; /** * @description Required for metered Features. * @enum {string} */ aggregation_type?: "count_agg" | "sum_agg" | "max_agg" | "unique_count_agg" | "weighted_sum_agg" | "latest_agg" | "custom_agg"; /** @description Required for metered Features. */ consumable?: boolean; /** @default false */ recurring: boolean; field_name?: string | null; expression?: string | null; custom_aggregator?: string | null; /** @enum {string|null} */ weighted_interval?: "seconds" | null; /** @enum {string|null} */ rounding_function?: "ceil" | "floor" | "round" | null; rounding_precision?: number | null; filters?: components["schemas"]["FeatureFilterInput"][]; }; FeatureCreateInput: { feature: components["schemas"]["FeatureBaseInput"] & { /** * @description Unique code used to identify the feature. * @example seats */ code: string; }; }; Feature: { feature: components["schemas"]["FeatureObject"]; }; FeatureUpdateInput: { feature: components["schemas"]["FeatureBaseInput"]; }; FeatureEvaluateExpressionInput: { /** @example round((ended_at - started_at) * units) */ expression: string; event: { /** @example storage */ code: string; /** @example 1651240791 */ timestamp?: number | string; properties: { [key: string]: string | number; }; }; }; FeatureEvaluateExpressionResult: { expression_result: { value: string | number; }; }; CouponObject: { /** * Format: uuid * @description Unique identifier of the coupon, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The name of the coupon. * @example Startup Deal */ name: string; /** * @description Unique code used to identify the coupon. * @example startup_deal */ code: string; /** * @description Description of the coupon. * @example I am a coupon description */ description?: string | null; /** * @description The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`. * * - If set to `fixed_amount`, the coupon represents a fixed amount discount. * - If set to `percentage`, the coupon represents a percentage-based discount. * @example fixed_amount * @enum {string} */ coupon_type: "fixed_amount" | "percentage"; /** * @description The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. * @example 5000 */ amount_cents?: number | null; /** * @description The currency of the coupon. This field is required only for coupon with `fixed_amount` type. * @example USD */ amount_currency?: components["schemas"]["CurrencyOrNull"]; /** * @description Indicates whether the coupon can be reused or not. If set to `true`, the coupon is reusable, meaning it can be applied multiple times to the same customer. If set to `false`, the coupon can only be used once and is not reusable. If not specified, this field is set to `true` by default. * @example true */ reusable: boolean; /** * @description The coupon is limited to specific plans. The possible values can be `true` or `false`. * @example true */ limited_plans: boolean; /** * @description An array of plan codes to which the coupon is applicable. By specifying the plan codes in this field, you can restrict the coupon's usage to specific plans only. * @example [ * "startup_plan" * ] */ plan_codes?: string[]; /** * @description The coupon is limited to specific features. The possible values can be `true` or `false`. * @example false */ limited_features: boolean; /** * @description An array of feature codes to which the coupon is applicable. By specifying the feature codes in this field, you can restrict the coupon's usage to specific metrics only. * @example [] */ feature_codes?: string[]; /** * @description The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. * @example null */ percentage_rate?: string | null; /** * @description The type of frequency for the coupon. It can have three possible values: `once`, `recurring`, or `forever`. * * - If set to `once`, the coupon is applicable only for a single use. * - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. * - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely. * @example recurring * @enum {string} */ frequency: "once" | "recurring" | "forever"; /** * @description Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type * @example 6 */ frequency_duration?: number | null; /** * @description Specifies the type of expiration for the coupon. It can have two possible values: `time_limit` or `no_expiration`. * * - If set to `time_limit`, the coupon has an expiration based on a specified time limit. * - If set to `no_expiration`, the coupon does not have an expiration date and remains valid indefinitely. * @example time_limit * @enum {string} */ expiration: "no_expiration" | "time_limit"; /** * Format: date-time * @description The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`. The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard. It indicates the exact moment when the coupon will expire and is no longer valid. * @example 2022-08-08T23:59:59Z */ expiration_at?: string | null; /** * Format: date-time * @description The date and time when the coupon was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the coupon was initially created. * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description This field indicates if the coupon has been terminated and is no longer usable. If it's not null, it won't be removed for existing customers using it, but it prevents the coupon from being applied in the future. * @example 2022-08-08T23:59:59Z */ terminated_at?: string | null; }; CouponsPaginated: { coupons: components["schemas"]["CouponObject"][]; meta: components["schemas"]["PaginationMeta"]; }; CouponBaseInput: { /** * @description The name of the coupon. * @example Startup Deal */ name?: string; /** * @description Unique code used to identify the coupon. * @example startup_deal */ code?: string; /** * @description Description of the coupon. * @example I am a coupon description */ description?: string | null; /** * @description The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`. * * - If set to `fixed_amount`, the coupon represents a fixed amount discount. * - If set to `percentage`, the coupon represents a percentage-based discount. * @example fixed_amount * @enum {string} */ coupon_type?: "fixed_amount" | "percentage"; /** * @description The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. * @example 5000 */ amount_cents?: number | null; /** * @description The currency of the coupon. This field is required only for coupon with `fixed_amount` type. * @example USD */ amount_currency?: components["schemas"]["CurrencyOrNull"]; /** * @description Indicates whether the coupon can be reused or not. If set to `true`, the coupon is reusable, meaning it can be applied multiple times to the same customer. If set to `false`, the coupon can only be used once and is not reusable. If not specified, this field is set to `true` by default. * @example false */ reusable?: boolean; /** * @description The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. * @example null */ percentage_rate?: string | null; /** * @description The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`. * * - If set to `once`, the coupon is applicable only for a single use. * - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. * - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely. * @example recurring * @enum {string} */ frequency?: "once" | "recurring" | "forever"; /** * @description Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type * @example 6 */ frequency_duration?: number | null; /** * @description Specifies the type of expiration for the coupon. It can have two possible values: `time_limit` or `no_expiration`. * * - If set to `time_limit`, the coupon has an expiration based on a specified time limit. * - If set to `no_expiration`, the coupon does not have an expiration date and remains valid indefinitely. * @example time_limit * @enum {string} */ expiration?: "no_expiration" | "time_limit"; /** * Format: date-time * @description The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`. The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard. It indicates the exact moment when the coupon will expire and is no longer valid. * @example 2022-08-08T23:59:59Z */ expiration_at?: string | null; /** @description Set coupon limitations to plans or specific metrics. */ applies_to?: { /** * @description An array of plan codes to which the coupon is applicable. By specifying the plan codes in this field, you can restrict the coupon's usage to specific plans only. * @example [ * "startup_plan" * ] */ plan_codes?: string[] | null; /** * @description An array of feature codes to which the coupon is applicable. By specifying the feature codes in this field, you can restrict the coupon's usage to specific metrics only. * @example [] */ feature_codes?: string[] | null; } | null; }; CouponCreateInput: { coupon: components["schemas"]["CouponBaseInput"]; }; Coupon: { coupon: components["schemas"]["CouponObject"]; }; CouponUpdateInput: { coupon: components["schemas"]["CouponBaseInput"]; }; FeeAmountDetails: { /** * @description The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan. * @example 10000 */ plan_amount_cents?: number; /** @description Graduated ranges, used for a `graduated` charge model. */ graduated_ranges?: { /** * @description Total units received in Nozle. * @example 10.0 */ units: string; /** * @description Lower value of a tier. It is either 0 or the previous range's `to_value + 1`. * @example 0 */ from_value: number; /** * @description Highest value of a tier. * - This value is higher than the from_value of the same tier. * - This value is null for the last tier. * @example 10 */ to_value: number | null; /** * @description Flat unit amount within a specified tier. * @example 1.0 */ flat_unit_amount: string; /** * @description Amount per unit within a specified tier. * @example 1.0 */ per_unit_amount: string; /** * @description Total amount of received units to be charged within a specified tier. * @example 10.0 */ per_unit_total_amount: string; /** * @description Total amount to be charged for a specific tier, taking into account the flat_unit_amount and the per_unit_total_amount. * @example 11.0 */ total_with_flat_amount: string; }[]; /** @description Graduated percentage ranges, used for a `graduated_percentage` charge model. */ graduated_percentage_ranges?: { /** * @description Total units received in Nozle. * @example 10.0 */ units: string; /** * @description Lower value of a tier. It is either 0 or the previous range's `to_value + 1`. * @example 0 */ from_value: number; /** * @description Highest value of a tier. * - This value is higher than the from_value of the same tier. * - This value is null for the last tier. * @example 10 */ to_value: number | null; /** * @description Flat unit amount within a specified tier. * @example 1.0 */ flat_unit_amount: string; /** * Format: ^[0-9]+.?[0-9]*$ * @description Percentage rate applied within a specified tier. * @example 1.0 */ rate: string; /** * @description Total amount of received units to be charged within a specified tier. * @example 10.0 */ per_unit_total_amount: string; /** * @description Total amount to be charged for a specific tier, taking into account the flat_unit_amount and the per_unit_total_amount. * @example 11.0 */ total_with_flat_amount: string; }[]; /** * @description The quantity of units that are provided free of charge for each billing period in a `package` charge model. * @example 10.0 */ free_units?: string; /** * @description The quantity of units that are not provided free of charge for each billing period in a `package` charge model. * @example 40.0 */ paid_units?: string; /** * @description The quantity of units included, defined for Package or Percentage charge model. * @example 1000 */ per_package_size?: number; /** * @description Total amount to charge for received paid_units, defined for Package or Percentage charge model. * @example 0.5 */ per_package_unit_amount?: string; /** * @description Total amount of received units to be charged for the Volume or Percentage charge model. * @example 10.0 */ per_unit_total_amount?: string; /** * @description The total units received in Nozle for the Percentage charge model. * @example 20.0 */ units?: string; /** * @description Total number of free events allowed for the Percentage charge model. * @example 10 */ free_events?: number; /** * Format: ^[0-9]+.?[0-9]*$ * @description Percentage rate applied for the Percentage charge model. * @example 1.0 */ rate?: string; /** * @description Total number of paid events for the Percentage charge model. * @example 20 */ paid_events?: number; /** * @description Fixed fee unit price per received paid_event for the Percentage charge model. * @example 1.0 */ fixed_fee_unit_amount?: string; /** * @description Total amount to charge for received paid_events for the Percentage charge model. * @example 20.0 */ fixed_fee_total_amount?: string; /** * @description Total adjustment amount linked to minimum and maximum spending per transaction for the Percentage charge model. * @example 20.0 */ min_max_adjustment_total_amount?: string; /** * @description The flat amount for a whole tier, excluding tax, for a `volume` charge model. * @example 0.5 */ per_unit_amount?: string; /** * @description The unit price, excluding tax, for a specific tier of a `volume` charge model. * @example 10.0 */ flat_unit_amount?: string; }; BaseAppliedTax: { /** * Format: uuid * @description Unique identifier of the applied tax, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the tax, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ tax_id: string | null; /** * @description Name of the tax. * @example TVA */ tax_name: string; /** * @description Unique code used to identify the tax associated with the API request. * @example french_standard_vat */ tax_code: string; /** * @description The percentage rate of the tax * @example 20 */ tax_rate: number; /** * @description Internal description of the tax * @example French standard VAT */ tax_description: string | null; /** * @description Amount of the tax * @example 2000 */ amount_cents: number; /** * @description Currency of the tax * @example USD */ amount_currency: components["schemas"]["Currency"]; /** * Format: date-time * @description The date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created. * @example 2022-09-14T16:35:31Z */ created_at: string; }; FeeAppliedTaxObject: { /** * Format: uuid * @description Unique identifier of the fee, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ fee_id?: string; } & components["schemas"]["BaseAppliedTax"]; PricingUnitDetailsObject: { /** * Format: uuid * @description Unique identifier of the pricing unit, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ pricing_unit_id: string; /** * @description The code of the pricing unit. * @example credits */ pricing_unit_code: string; /** * @description The short name of the pricing unit. Will be used as currency name in the UI and PDFs. * @example CR */ short_name: string; /** * @description The amount in cents in the pricing unit. * @example 200 */ amount_cents: number; /** * @description The precise amount in cents in the pricing unit. * @example 200.0 */ precise_amount_cents: string; /** * @description The unit amount in cents in the pricing unit. * @example 100 */ unit_amount_cents: number; /** * @description The precise unit amount in the pricing unit. * @example 100.0 */ precise_unit_amount: string; /** * @description The conversion rate from pricing units to the plan's currency. * @example 0.5 */ conversion_rate: string; } | null; /** @description Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation. */ PresentationBreakdownsObject: { /** @description Key value list of event properties used for presentation grouping. */ presentation_by?: { [key: string]: string; }; /** * @description The number of units consumed for a specific presentation group. * @example 9.0 */ units?: string; }[]; FeeObject: { /** * Format: uuid * @description Unique identifier assigned to the fee within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the fee's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the charge that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ charge_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the charge filter that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ charge_filter_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the fixed charge that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ fixed_charge_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the invoice that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the true-up fee when a minimum has been set to the charge. This identifier helps to distinguish and manage the true-up fee associated with the charge, which may be applicable when a minimum threshold or limit is set for the charge amount. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ true_up_fee_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the parent fee on which the true-up fee is assigned. This identifier establishes the relationship between the parent fee and the associated true-up fee. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ true_up_parent_fee_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the subscription, created by Nozle. This field is specifically displayed when the fee type is charge or subscription. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id?: string | null; /** * Format: uuid * @description Unique identifier assigned to the customer, created by Nozle. This field is specifically displayed when the fee type is charge or subscription. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id?: string | null; /** * @description Unique identifier assigned to the customer in your application. This field is specifically displayed when the fee type is charge or subscription. * @example external_id */ external_customer_id?: string | null; /** * @description Unique identifier assigned to the subscription in your application. This field is specifically displayed when the fee type is charge or subscription. * @example external_id */ external_subscription_id?: string | null; /** * @description The cost of this specific fee, excluding any applicable taxes. * @example 100 */ amount_cents: number; /** * @description The cost of this specific fee, excluding any applicable taxes, with precision. * @example 1.0001 */ precise_amount?: string; /** * @description The cost of this specific fee, including any applicable taxes, with precision. * @example 1.0212 */ precise_total_amount?: string; /** * @description The currency of this specific fee. It indicates the monetary unit in which the fee's cost is expressed. * @example EUR */ amount_currency: components["schemas"]["Currency"]; /** * @description The cost of the tax associated with this specific fee. * @example 20 */ taxes_amount_cents: number; /** * @description The cost of the tax associated with this specific fee, with precision. * @example 0.20123 */ taxes_precise_amount?: string; /** * @description The tax rate associated with this specific fee. * @example 20 */ taxes_rate: number; /** * @description The number of units used to charge the customer. This field indicates the quantity or count of units consumed or utilized in the context of the charge. It helps in determining the basis for calculating the fee or cost associated with the usage of the service or product provided to the customer. * @example 0.32 */ units: string; /** * @description The unit amount of the fee per unit, with precision. * @example 312.5 */ precise_unit_amount: string; /** * @description The total number of units that have been aggregated for this specific fee. * @example 0.32 */ total_aggregated_units: string | null; /** * @description The cost of this specific fee, including any applicable taxes. * @example 120 */ total_amount_cents: number; /** * @description The currency of this specific fee, including any applicable taxes. * @example EUR */ total_amount_currency: components["schemas"]["Currency"]; /** * @description The number of events that have been sent and used to charge the customer. This field indicates the count or quantity of events that have been processed and considered in the charging process. * @example 23 */ events_count?: number | null; /** * @description Flag that indicates whether the fee was paid in advance. It serves as a boolean value, where `true` represents that the fee was paid in advance (straightaway), and `false` indicates that the fee was not paid in arrears (at the end of the period). * @example true */ pay_in_advance: boolean; /** * @description Flag that indicates whether the fee was included on the invoice. It serves as a boolean value, where `true` represents that the fee was included on the invoice, and `false` indicates that the fee was not included on the invoice. * @example true */ invoiceable: boolean; /** * Format: date-time * @description The beginning date of the period that the fee covers. It is applicable only to `subscription`, `charge`, `fixed_charge` and `commitment` fees. This field indicates the start date of the billing period or subscription period associated with the fee. * @example 2022-04-29T08:59:51Z */ from_date?: string | null; /** * Format: date-time * @description The ending date of the period that the fee covers. It is applicable only to `subscription`, `charge`, `fixed_charge` and `commitment` fees. This field indicates the end date of the billing period or subscription period associated with the fee. * @example 2022-05-29T08:59:51Z */ to_date?: string | null; /** * @description Indicates the payment status of the fee. It represents the current status of the payment associated with the fee. The possible values for this field are `pending`, `succeeded`, `failed` and `refunded`. * @example pending * @enum {string} */ payment_status: "pending" | "succeeded" | "failed" | "refunded"; /** * Format: date-time * @description The date and time when the fee was created. It is provided in Coordinated Universal Time (UTC) format. * @example 2022-08-24T14:58:59Z */ created_at?: string | null; /** * Format: date-time * @description The date and time when the payment for the fee was successfully processed. It is provided in Coordinated Universal Time (UTC) format. * @example 2022-08-24T14:58:59Z */ succeeded_at?: string | null; /** * Format: date-time * @description The date and time when the payment for the fee failed to process. It is provided in Coordinated Universal Time (UTC) format. * @example 2022-08-24T14:58:59Z */ failed_at?: string | null; /** * Format: date-time * @description The date and time when the payment for the fee was refunded. It is provided in Coordinated Universal Time (UTC) format * @example 2022-08-24T14:58:59Z */ refunded_at?: string | null; /** * @description Unique identifier assigned to the transaction. This field is specifically displayed when the fee type is `charge` and the payment for the fee is made in advance (`pay_in_advance` is set to `true`). * @example transaction_1234567890 */ event_transaction_id?: string | null; /** * @description The description of the fee. * @example Fee description */ description?: string | null; /** * @description The coupon amount applied to the fee, with precision. * @example 0.0 */ precise_coupons_amount_cents?: string; /** * @description The sub total of the fee excluding taxes, in cents. * @example 100 */ sub_total_excluding_taxes_amount_cents: number; /** * @description The sub total of the fee excluding taxes, with precision. * @example 100.0 */ sub_total_excluding_taxes_precise_amount_cents: string; /** @description List of all unit amount details for calculating the fee. */ amount_details?: components["schemas"]["FeeAmountDetails"]; /** * @description Indicates if the fee belongs to self-billed invoice. Self-billing is a process where an organization creates the invoice on behalf of the partner. * @example false */ self_billed?: boolean; /** @description Item attached to the fee */ item: { /** * @description The fee type. Possible values are `add-on`, `charge`, `fixed_charge`, `credit`, `subscription` or `commitment`. * @example subscription * @enum {string} */ type: "charge" | "fixed_charge" | "add_on" | "subscription" | "credit" | "commitment"; /** * @description The code of the fee item. It can be the code of the `add-on`, the code of the `charge`, the code of the `fixed_charge`, the code of the `credit` or the code of the `subscription`. * @example startup */ code: string; /** * @description The name of the fee item. The value depends on the type of the fee item: * * - If the fee item is a `charge`, it is the feature name. * - If the fee item is a `add-on`, it is the add-on name. * - If the fee item is a `credit`, it is the wallet transaction name if set, or `"credit"` if not. * - If the fee item is a `fixed_charge`, it is the fixed charge add-on name. * - For all the other fee items, it is the subscription plan name. * @example Startup */ name: string; /** * @description The description of the fee item. The value depends on the type of the fee item: * * - If the fee item is a `charge`, it is the feature description. * - If the fee item is a `add-on`, it is the add-on description. * - If the fee item is a `credit`, it is always `"credit"`. * - If the fee item is a `fixed_charge`, it is the fixed charge add-on description. * - For all the other fee items, it is the subscription plan description. * @example Startup */ description?: string | null; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, we'll fallback to a value that depends on the type of the fee items: * * - If the fee item is a `charge`, we'll fallback to the `invoice_display_name` of the `charge` or the feature name if no `invoice_display_name` is set. * - If the fee item is a `add-on`, we'll fallback to the `invoice_name` of the `add-on` or the `name` of the `add-on`. * - If the fee item is a `credit`, we'll fallback to the wallet transaction name if set, or `credit` if not. * - If the fee item is a `fixed_charge`, we'll fallback to the `invoice_display_name` of the `fixed_charge` or the `invoice_name` of the `fixed_charge_add_on` if no `invoice_display_name` is set. * - For all the other fee items, we'll fallback to the `invoice_display_name` of the subscription plan. * @example Setup Fee (SF1) */ invoice_display_name?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the actual charge filter values will be used as the default display name. * @example AWS eu-east-1 */ filter_invoice_display_name?: string | null; /** @description Key value list of event properties */ filters?: { [key: string]: string[]; } | null; /** * Format: uuid * @description Unique identifier of the fee item, created by Nozle. It can be the identifier of the `add-on`, the `charge`, the `credit`, the `subscription` or the `commitment`. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ item_id: string; /** * @description The type of the fee item. Possible values are `AddOn`, `Feature`, `WalletTransaction`, `Subscription`. * @example Subscription * @enum {string} */ item_type: "AddOn" | "Feature" | "Subscription" | "WalletTransaction"; /** @description Key value list of event properties aggregated by the charge model */ grouped_by?: { [key: string]: string; }; }; /** @description List of fee applied taxes */ applied_taxes?: components["schemas"]["FeeAppliedTaxObject"][]; /** @description Details about the pricing unit used and amounts for this fee. */ pricing_unit_details?: components["schemas"]["PricingUnitDetailsObject"]; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; original_fee_id?: string | null; }; CreditNoteItemObject: { /** * Format: uuid * @description The credit note's item unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The credit note's item amount, expressed in cents. * @example 100 */ amount_cents: number; /** * @description The credit note's item currency. * @example EUR */ amount_currency: components["schemas"]["Currency"]; /** @description The fee object related to the credit note item. */ fee: components["schemas"]["FeeObject"]; precise_amount_cents?: string; }; CreditNoteAppliedTaxObject: { /** * Format: uuid * @description Unique identifier of the credit note, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ credit_note_id?: string; /** @example 100 */ base_amount_cents?: number; } & components["schemas"]["BaseAppliedTax"]; /** * @example US * @enum {string|null} */ CountryOrNull: null | "AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AO" | "AQ" | "AR" | "AS" | "AT" | "AU" | "AW" | "AX" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BL" | "BM" | "BN" | "BO" | "BQ" | "BR" | "BS" | "BT" | "BV" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CV" | "CW" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GG" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GS" | "GT" | "GU" | "GW" | "GY" | "HK" | "HM" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IM" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JE" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MF" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PN" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "SS" | "ST" | "SV" | "SX" | "SY" | "SZ" | "TC" | "TD" | "TF" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "UM" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "YE" | "YT" | "ZA" | "ZM" | "ZW"; /** * @example America/Los_Angeles * @enum {string|null} */ TimezoneOrNull: null | "UTC" | "Africa/Algiers" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Monrovia" | "Africa/Nairobi" | "America/Argentina/Buenos_Aires" | "America/Bogota" | "America/Caracas" | "America/Chicago" | "America/Chihuahua" | "America/Denver" | "America/Godthab" | "America/Guatemala" | "America/Guyana" | "America/Halifax" | "America/Indiana/Indianapolis" | "America/Juneau" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Mazatlan" | "America/Mexico_City" | "America/Monterrey" | "America/Montevideo" | "America/New_York" | "America/Phoenix" | "America/Puerto_Rico" | "America/Regina" | "America/Santiago" | "America/Sao_Paulo" | "America/St_Johns" | "America/Tijuana" | "Asia/Almaty" | "Asia/Baghdad" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Chongqing" | "Asia/Colombo" | "Asia/Dhaka" | "Asia/Hong_Kong" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Kathmandu" | "Asia/Kolkata" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuwait" | "Asia/Magadan" | "Asia/Muscat" | "Asia/Novosibirsk" | "Asia/Rangoon" | "Asia/Riyadh" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Tokyo" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Cape_Verde" | "Atlantic/South_Georgia" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Darwin" | "Australia/Hobart" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Europe/Amsterdam" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Helsinki" | "Europe/Istanbul" | "Europe/Kaliningrad" | "Europe/Kiev" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Madrid" | "Europe/Minsk" | "Europe/Moscow" | "Europe/Paris" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/Sarajevo" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zurich" | "GMT+12" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Chatham" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Majuro" | "Pacific/Midway" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Port_Moresby" | "Pacific/Tongatapu"; /** @description Configuration specific to the payment provider, utilized for billing the customer. This object contains settings and parameters necessary for processing payments and invoicing the customer. */ CustomerBillingConfiguration: { /** * @description The grace period, expressed in days, for the invoice. This period refers to the additional time granted to the customer beyond the invoice due date to adjust usage and line items * @example 3 */ invoice_grace_period?: number | null; /** * @description Defines whether the issuing date follows the current billing period's end date or the next period starting date. * @default null * @example next_period_start * @enum {string|null} */ subscription_invoice_issuing_date_anchor: "current_period_end" | "next_period_start" | null; /** * @description The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period. * @default null * @example keep_anchor * @enum {string|null} */ subscription_invoice_issuing_date_adjustment: "align_with_finalization_date" | "keep_anchor" | null; /** * @description The payment provider utilized to initiate payments for invoices issued by Nozle. * Accepted values: `stripe`, `razorpay`, `adyen`, `gocardless`, `cashfree`, `flutterwave`, `moneyhash` or null. This field is required if you intend to assign a `provider_customer_id`. * @example stripe * @enum {string|null} */ payment_provider?: "stripe" | "razorpay" | "adyen" | "gocardless" | "cashfree" | "flutterwave" | "moneyhash" | null; /** * @description Unique code used to identify a payment provider connection. * @example stripe-eu-1 */ payment_provider_code?: string | null; /** * @description The customer ID within the payment provider's system. If this field is not provided, Nozle has the option to create a new customer record within the payment provider's system on behalf of the customer * @example cus_12345 */ provider_customer_id?: string | null; /** * @description Set this field to `true` if you want to create the customer in the payment provider synchronously with the customer creation process in Nozle. This option is applicable only when the `provider_customer_id` is `null` and the customer is automatically created in the payment provider through Nozle. By default, the value is set to `false` * @example true */ sync?: boolean; /** * @description Set this field to `true` if you want to create a customer record in the payment provider's system. This option is applicable only when the `provider_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false` * @example true */ sync_with_provider?: boolean; /** * @description The document locale, specified in the ISO 639-1 format. This field represents the language or locale used for the documents issued by Nozle * @example fr */ document_locale?: string | null; /** * @description Specifies the available payment methods that can be used for this customer when `payment_provider` is set to `stripe`. The `provider_payment_methods` field is an array that allows multiple payment options to be defined. If this field is not explicitly set, the payment methods will be set to `card`. For now, possible values are `card`, `sepa_debit`, `us_bank_account`, `bacs_debit`, `boleto`, `link`, `crypto` and `customer_balance`. Note that when `link` is selected, `card` should also be provided in the array. When `customer_balance` is selected, no other payment can be selected. * @example [ * "card", * "sepa_debit", * "us_bank_account", * "bacs_debit", * "link", * "boleto", * "crypto", * "customer_balance" * ] */ provider_payment_methods?: string[] | null; }; /** @description Configuration specific to the payment provider, utilized for billing the customer. This object contains settings and parameters necessary for processing payments and invoicing the customer. */ Address: { /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string | null; /** * @description The second line of the billing address * @example null */ address_line2?: string | null; /** * @description The city of the customer's billing address * @example Woodland Hills */ city?: string | null; /** * @description Country code of the customer's billing address. Format must be ISO 3166 (alpha-2) * @example US */ country?: components["schemas"]["CountryOrNull"]; /** * @description The state of the customer's billing address * @example CA */ state?: string | null; /** * @description The zipcode of the customer's billing address * @example 91364 */ zipcode?: string | null; }; /** @description Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format */ CustomerMetadata: { /** * Format: uuid * @description A unique identifier for the customer metadata object in the Nozle application. Can be used to update a key-value pair * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The metadata object key * @example Purchase Order */ key: string; /** * @description The metadata object value * @example 123456789 */ value: string; /** * @description Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice. * @example true */ display_in_invoice: boolean; /** * Format: date-time * @description The date of the metadata object creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the metadata object was created * @example 2022-04-29T08:59:51Z */ created_at: string; }; CustomerBaseObject: { /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The unique identifier assigned to the customer within the organization's scope. This identifier is used to track and reference the customer's order of creation within the organization's system. It ensures that each customer has a distinct `sequential_id`` associated with them, allowing for easy identification and sorting based on the order of creation * @example 1 */ sequential_id: number; /** * @description A concise and unique identifier for the customer, formed by combining the Organization's `name`, `id`, and customer's `sequential_id` * @example LAG-1234-001 */ slug: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_id: string; /** * @description The unique code of the billing entity associated with the customer. * @example acme_corp */ billing_entity_code?: string; /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string | null; /** * @description The second line of the billing address * @example null */ address_line2?: string | null; /** @description The customer's applicable timezone, used for billing purposes in their local time. */ applicable_timezone: components["schemas"]["Timezone"]; /** * @description The city of the customer's billing address * @example Woodland Hills */ city?: string | null; /** * @description Country code of the customer's billing address. Format must be ISO 3166 (alpha-2) * @example US */ country?: components["schemas"]["CountryOrNull"]; /** * @description Currency of the customer. Format must be ISO 4217 * @example USD */ currency?: components["schemas"]["CurrencyOrNull"]; /** * Format: email * @description The email of the customer * @example dinesh@piedpiper.test */ email?: string | null; /** * @description The legal company name of the customer * @example Coleman-Blair */ legal_name?: string | null; /** * @description The legal company number of the customer * @example 49-008-2965 */ legal_number?: string | null; /** * @description The logo URL of the customer * @example http://hooli.com/logo.png */ logo_url?: string | null; /** * @description The full name of the customer * @example Gavin Belson */ name?: string | null; /** * @description First name of the customer * @example Gavin */ firstname?: string | null; /** * @description Last name of the customer * @example Belson */ lastname?: string | null; /** * @description The type of the account. It can have one of the following values: * - `customer`: the account is a customer. * - `partner`: the account is a partner. * @example customer * @enum {string} */ account_type?: "customer" | "partner"; /** * @description The type of the customer. It can have one of the following values: * - `company`: the customer is a company. * - `individual`: the customer is an individual. * @enum {string|null} */ customer_type?: "company" | "individual" | null; /** * @description The phone number of the customer * @example 1-171-883-3711 x245 */ phone?: string | null; /** * @description The state of the customer's billing address * @example CA */ state?: string | null; /** * @description The tax identification number of the customer * @example EU123456789 */ tax_identification_number?: string | null; /** @description The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone */ timezone?: components["schemas"]["TimezoneOrNull"]; /** * @description The custom website URL of the customer * @example http://hooli.com */ url?: string | null; /** * @description The zipcode of the customer's billing address * @example 91364 */ zipcode?: string | null; /** * @description The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized. * @example 30 */ net_payment_term?: number | null; /** * Format: date-time * @description The date of the customer creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the customer object was created * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description The date of the customer update, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The update_date provides a standardized and internationally recognized timestamp for when the customer object was updated * @example 2022-04-29T08:59:51Z */ updated_at?: string; /** * @description Specifies how invoices with a zero total amount should be handled: * - `inherit`: (Default) Follows the organization-level configuration. * - `finalize`: Invoices are issued and finalized even if the total amount is zero. * - `skip`: Invoices with a total amount of zero are not finalized. * @example inherit * @enum {string} */ finalize_zero_amount_invoice?: "inherit" | "skip" | "finalize"; /** * @description Set to true to exclude all invoice custom sections from PDF generation for this customer only. * @example false */ skip_invoice_custom_sections?: boolean; /** * Format: date-time * @description Core 11.16.0. When the [dunning policy](/guides/billing/dunning) blocked the customer: an unpaid invoice is past the grace of its plan and the campaign ends with `block`. The Engine then answers `402` `customer_payment_overdue` for the customer. `null` when not blocked. * @example null */ dunning_blocked_at?: string | null; /** * @description Core 11.16.0. Day of the dunning timeline that the customer's furthest unpaid invoice is on. `null` without a dunned invoice. * @example null */ dunning_day?: number | null; /** * Format: date-time * @description Core 11.16.0. When the next step of the dunning policy runs, a retry included (only after a soft decline). `null` when none is planned. * @example null */ dunning_next_action_at?: string | null; billing_configuration?: components["schemas"]["CustomerBillingConfiguration"]; shipping_address?: components["schemas"]["Address"]; metadata?: components["schemas"]["CustomerMetadata"][]; external_salesforce_id?: string | null; /** * @description Set for a customer who pays each invoice by link (Razorpay, or Stripe without a saved payment method) when no email can carry the link: the billing entity has no email, or the customer has none. `null` otherwise. While it is set, the automatic payment request of an invoice is skipped and Nozle sends `invoice.payment_failure` for that invoice with the same value as `provider_error.error_code`. * @example null * @enum {string|null} */ payment_collection_warning?: "billing_entity_email_missing" | "customer_email_missing" | null; }; /** * @description Custom metadata stored as key-value pairs. * Keys are strings (max 100 characters), values can be strings (max 255 characters) or null. * @example { * "external_id": "ext-123", * "synced_at": "2024-01-15", * "source": null * } */ MetadataObject: { [key: string]: string | null; } | null; CreditNoteErrorDetailsObject: { /** * Format: uuid * @description The credit note error details unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The type of the error. * @example tax_error * @enum {string} */ error_code: "not_provided" | "tax_error" | "tax_voiding_error" | "invoice_generation_error"; /** @description The details of the error. */ details: Record; }; CreditNoteObject: { /** * Format: uuid * @description The credit note unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The unique code of the billing entity associated with the credit note. * @example acme_corp */ billing_entity_code: string; /** * @description The sequential identifier of the credit note, specifically scoped on the associated invoice. It provides a unique numerical identifier for the credit note within the context of the invoice. * @example 2 */ sequential_id: number; /** * @description The credit note unique number. * @example LAG-1234-CN2 */ number: string; /** * Format: uuid * @description Unique identifier assigned to the invoice that the credit note belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string; /** * @description The invoice unique number, related to the credit note. * @example LAG-1234 */ invoice_number: string; /** * Format: date * @description The date of creation of the credit note. It follows the ISO 8601 date format and provides the specific date when the credit note was created. * @example 2022-12-06 */ issuing_date: string; /** * @description The status of the credit portion of the credit note. It indicates the current state or condition of the credit amount associated with the credit note. The possible values for this field are: * * - `available`: this status indicates that an amount remains available for future usage. The credit can be applied towards future transactions or invoices. * - `consumed`: this status indicates that the credit amount has been fully consumed. The remaining amount is 0, indicating that the credit has been utilized in its entirety. * - `voided`: this status indicates that the remaining amount of the credit cannot be used any further. The credit has been voided and is no longer available for application or redemption. * @example available * @enum {string|null} */ credit_status?: "available" | "consumed" | "voided" | null; /** * @description The status of the refund portion of the credit note. It indicates the current state or condition of the refund associated with the credit note. The possible values for this field are: * * - `pending`: this status indicates that the refund is pending execution. The refund request has been initiated but has not been processed or completed yet. * - `succeeded`: this status indicates that the refund has been successfully executed. The refund amount has been processed and returned to the customer or the designated recipient. * - `failed`: this status indicates that the refund failed to execute. The refund request encountered an error or unsuccessful processing, and the refund amount could not be returned. * @example pending * @enum {string|null} */ refund_status?: "pending" | "succeeded" | "failed" | null; /** * @description The reason of the credit note creation. * Possible values are `duplicated_charge`, `product_unsatisfactory`, `order_change`, `order_cancellation`, `fraudulent_charge` or `other`. * @example other * @enum {string} */ reason: "duplicated_charge" | "product_unsatisfactory" | "order_change" | "order_cancellation" | "fraudulent_charge" | "other"; /** * @description The description of the credit note. * @example Free text */ description?: string | null; /** * @description The currency of the credit note. * @example EUR */ currency: components["schemas"]["Currency"]; /** * @description The total amount of the credit note, expressed in cents. * @example 120 */ total_amount_cents: number; /** * @description The tax amount of the credit note, expressed in cents. * @example 20 */ taxes_amount_cents: number; /** * @description The tax rate associated with this specific credit note. * @example 20 */ taxes_rate: number; /** * @description The subtotal of the credit note excluding any applicable taxes, expressed in cents. * @example 100 */ sub_total_excluding_taxes_amount_cents: number; /** * @description The remaining credit note amount, expressed in cents. * @example 100 */ balance_amount_cents: number; /** * @description The credited amount of the credit note, expressed in cents. * @example 100 */ credit_amount_cents: number; /** * @description The refunded amount of the credit note, expressed in cents. * @example 0 */ refund_amount_cents: number; /** * @description The ofsetted amount (deducted from the invoice balance) of the credit note, expressed in cents. * @example 0 */ offset_amount_cents: number; /** * @description The part of `refund_amount_cents` the merchant paid back outside any payment provider, for example by bank transfer or in cash, expressed in cents. It is never sent to a provider. A credit note refunded only out of band has `refund_status` `succeeded` at once. 0 when everything was refunded online. Core 11.46.0; absent on older Cores. * @example 0 */ out_of_band_refund_amount_cents?: number; /** * @description The merchant's reference for the out-of-band refund, for example a bank transfer ID. Core 11.46.0; absent on older Cores. * @example null */ out_of_band_refund_reference?: string | null; /** * Format: date-time * @description When the out-of-band refund was made. `null` without an out-of-band refund. Core 11.46.0; absent on older Cores. * @example null */ out_of_band_refunded_at?: string | null; /** * @description The pro-rated amount of the coupons applied to the source invoice. * @example 20 */ coupons_adjustment_amount_cents: number; /** * Format: date-time * @description The date when the credit note was created. It is expressed in Coordinated Universal Time (UTC). * @example 2022-09-14T16:35:31Z */ created_at: string; /** * Format: date-time * @description The date when the credit note was last updated. It is expressed in Coordinated Universal Time (UTC). * @example 2022-09-14T16:35:31Z */ updated_at: string; /** * @description The PDF file of the credit note. * @example https://billing.example.com/credit-notes/example.pdf */ file_url?: string | null; /** @description Array of credit note's items. */ items?: components["schemas"]["CreditNoteItemObject"][]; applied_taxes?: components["schemas"]["CreditNoteAppliedTaxObject"][]; /** * @description Indicates if the credit note belongs to self-billed invoice. Self-billing is a process where an organization creates the invoice on behalf of the partner. * @example false */ self_billed?: boolean; customer?: components["schemas"]["CustomerBaseObject"]; metadata?: components["schemas"]["MetadataObject"]; error_details?: components["schemas"]["CreditNoteErrorDetailsObject"][] | null; }; CreditNotesPaginated: { credit_notes: components["schemas"]["CreditNoteObject"][]; meta: components["schemas"]["PaginationMeta"]; }; /** * @description Metadata to set as key-value pairs. Keys are strings (max 100 characters), values can be strings (max 255 characters) or null. * @example { * "external_id": "ext-123", * "synced_at": "2024-01-15" * } */ MetadataInput: { [key: string]: string | null; }; CreditNoteCreateInput: { credit_note: { /** * Format: uuid * @description The invoice unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string; /** * @description The reason of the credit note creation. * Possible values are `duplicated_charge`, `product_unsatisfactory`, `order_change`, `order_cancellation`, `fraudulent_charge` or `other`. * @example duplicated_charge * @enum {string|null} */ reason?: "duplicated_charge" | "product_unsatisfactory" | "order_change" | "order_cancellation" | "fraudulent_charge" | "other" | null; /** * @description The description of the credit note. * @example description */ description?: string; /** * @description The total amount to be credited to the customer balance for discounts on future invoices. For a total or partial refund, credit or offset, the amount in cents must include both the item amount and the applicable tax. The refunded, credited and offsetted amounts should always balance. The total, including taxes, cannot exceed the invoice’s total fees.” * @example 100 */ credit_amount_cents?: number | null; /** * @description The total amount to be refunded immediately to the payment method used by the customer. For a total or partial refund, credit or offset, the amount in cents must include both the item amount and the applicable tax. The refunded, credited and offsetted amounts should always balance. The total, including taxes, cannot exceed the invoice’s total fees.” * @example 500 */ refund_amount_cents?: number | null; /** * @description The total amount to be immediately deducted from the invoice balance. For a total or partial refund, credit or offset, the amount in cents must include both the item amount and the applicable tax. The refunded, credited and offsetted amounts should always balance. The total, including taxes, cannot exceed the invoice’s total fees.” * @example 200 */ offset_amount_cents?: number | null; /** * @description The list of credit note's items. * @example [ * { * "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", * "amount_cents": 100 * }, * { * "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", * "amount_cents": 500 * }, * { * "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a92", * "amount_cents": 200 * } * ] */ items: { /** * Format: uuid * @description The fee unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ fee_id: string; /** * @description This is the amount of the credit note item excluding taxes, expressed in cents. * @example 100 */ amount_cents: number; }[]; metadata?: components["schemas"]["MetadataInput"]; }; }; CreditNoteExtendedObject: components["schemas"]["CreditNoteObject"] & { customer?: components["schemas"]["CustomerBaseObject"]; precise_total_amount_cents?: string; precise_taxes_amount_cents?: string; xml_url?: string | null; }; CreditNoteExtended: { credit_note: components["schemas"]["CreditNoteExtendedObject"]; }; CreditNoteUpdateInput: { credit_note: { /** * @description The status of the refund portion of the credit note. It indicates the current state or condition of the refund associated with the credit note. The possible values for this field are: * * - `pending`: this status indicates that the refund is pending execution. The refund request has been initiated but has not been processed or completed yet. * - `succeeded`: this status indicates that the refund has been successfully executed. The refund amount has been processed and returned to the customer or the designated recipient. * - `failed`: this status indicates that the refund failed to execute. The refund request encountered an error or unsuccessful processing, and the refund amount could not be returned. * @example succeeded * @enum {string} */ refund_status: "pending" | "succeeded" | "failed"; metadata?: components["schemas"]["MetadataInput"]; }; }; CreditNote: { credit_note: components["schemas"]["CreditNoteObject"]; }; CreditNoteEstimateInput: { credit_note: { /** * Format: uuid * @description The invoice unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string; /** * @description The list of credit note's items. * @example [ * { * "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", * "amount_cents": 10 * }, * { * "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", * "amount_cents": 5 * } * ] */ items: { /** * Format: uuid * @description The fee unique identifier, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ fee_id: string; /** * @description The amount of the credit note item, expressed in cents. * @example 10 */ amount_cents: number; }[]; }; }; CreditNoteEstimated: { estimated_credit_note: { /** * Format: uuid * @description Unique identifier assigned to the invoice that the credit note belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string; /** * @description The invoice unique number, related to the credit note. * @example LAG-1234 */ invoice_number: string; /** * @description The currency of the credit note. * @example EUR */ currency: components["schemas"]["Currency"]; /** * @description The tax amount of the credit note, expressed in cents. * @example 20 */ taxes_amount_cents: number; /** * @description The precise tax amount of the credit note, expressed in cents with decimal precision. * @example 20.1 */ precise_taxes_amount_cents: number; /** * @description The tax rate associated with this specific credit note. * @example 20 */ taxes_rate: number; /** * @description The subtotal of the credit note excluding any applicable taxes, expressed in cents. * @example 100 */ sub_total_excluding_taxes_amount_cents: number; /** * @description The credited amount of the credit note, expressed in cents. * @example 100 */ max_creditable_amount_cents: number; /** * @description The refunded amount of the credit note, expressed in cents. * @example 0 */ max_refundable_amount_cents: number; /** * @description The ofsetted amount of the credit note, expressed in cents. * @example 0 */ max_offsettable_amount_cents: number; /** * @description The pro-rated amount of the coupons applied to the source invoice. * @example 20 */ coupons_adjustment_amount_cents: number; /** * @description The precise pro-rated amount with decimal precision of the coupons applied to the source invoice. * @example 20.1 */ precise_coupons_adjustment_amount_cents: number; /** @description Array of credit note's items. */ items: { /** * @description The credit note's item amount, expressed in cents. * @example 100 */ amount_cents: number; /** * Format: uuid * @description Unique identifier assigned to the fee within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the fee's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ fee_id: string | null; }[]; applied_taxes?: { /** * Format: uuid * @description Unique identifier of the tax, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ tax_id?: string; /** * @description Name of the tax. * @example TVA */ tax_name?: string; /** * @description Unique code used to identify the tax associated with the API request. * @example french_standard_vat */ tax_code?: string; /** * @description The percentage rate of the tax * @example 20 */ tax_rate?: number; /** * @description Internal description of the taxe * @example French standard VAT */ tax_description?: string; /** @example 100 */ base_amount_cents?: number; /** * @description Amount of the tax * @example 2000 */ amount_cents?: number; /** * @description Currency of the tax * @example USD */ amount_currency?: components["schemas"]["Currency"]; }[]; }; }; ApiErrorNotAllowed: { /** * Format: int32 * @example 422 */ status: number; /** @example Unprocessable Entity */ error: string; /** @example not_allowed */ code: string; }; CreditNoteMetadataResponse: { metadata: components["schemas"]["MetadataObject"]; }; /** @description Configuration specific to the accounting and tax integrations. This object contains settings and parameters necessary for syncing documents and payments. */ IntegrationCustomer: { /** * Format: uuid * @description A unique identifier for the integration customer object in the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The integration type used for accounting and tax syncs. * Accepted values: `anrok`. * @example anrok * @enum {string} */ type: "anrok"; /** * @description Unique code used to identify an integration connection. * @example anrok1 */ integration_code: string; /** * @description The customer ID within the integration's system. If this field is not provided, Nozle has the option to create a new customer record within the integration's system on behalf of the customer. * @example cus_12345 */ external_customer_id: string; /** * @description Set this field to `true` if you want to create a customer record in the integration's system. This option is applicable only when the `external_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false` * @example true */ sync_with_provider?: boolean | null; }; CustomerObject: components["schemas"]["CustomerBaseObject"] & { integration_customers?: components["schemas"]["IntegrationCustomer"][]; external_salesforce_id?: string | null; }; ErrorDetailObject: { /** * Format: uuid * @description Unique identifier assigned to the error_detail within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the error's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string | null; /** * @description Code that specifies part of the application / connection, where the error originally happened * @example tax_error */ error_code: string; /** * @description Key value list of more elaborated error detail, where by the key of error_code an external service error details are stored * @example { * "tax_error": "taxDateTooFarInFuture" * } */ details: { [key: string]: string; }; }; CustomerObjectExtended: components["schemas"]["CustomerObject"] & { metadata?: components["schemas"]["CustomerMetadata"][]; /** @description List of customer taxes */ taxes?: components["schemas"]["TaxObject"][]; /** @description The customer’s invoice custom section used for generating invoices. */ applicable_invoice_custom_sections?: components["schemas"]["InvoiceCustomSectionObject"][]; /** @description List of errors with details that might have been raised while processing backgroud actions for the customers */ error_details?: components["schemas"]["ErrorDetailObject"][]; }; CustomersPaginated: { customers: components["schemas"]["CustomerObjectExtended"][]; meta: components["schemas"]["PaginationMeta"]; }; CustomerCreateInput: { customer: { /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_id: string; /** * @description The unique code of the billing entity to associate with the customer. If not provided, the default billing entity will be used. * @example acme_corp */ billing_entity_code?: string | null; /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string | null; /** * @description The second line of the billing address * @example */ address_line2?: string | null; /** * @description The city of the customer's billing address * @example Woodland Hills */ city?: string | null; /** * @description Country code of the customer's billing address. Format must be ISO 3166 (alpha-2) * @example US */ country?: components["schemas"]["CountryOrNull"]; /** @description Currency of the customer. Format must be ISO 4217 */ currency?: components["schemas"]["CurrencyOrNull"]; /** * Format: email * @description The email of the customer * @example dinesh@piedpiper.test */ email?: string | null; /** * @description The legal company name of the customer * @example Coleman-Blair */ legal_name?: string | null; /** * @description The legal company number of the customer * @example 49-008-2965 */ legal_number?: string | null; /** * @description The logo URL of the customer * @example http://hooli.com/logo.png */ logo_url?: string | null; /** * @description The full name of the customer * @example Gavin Belson */ name?: string | null; /** * @description First name of the customer * @example Gavin */ firstname?: string | null; /** * @description Last name of the customer * @example Belson */ lastname?: string | null; /** * @description The type of the account. It can have one of the following values: * - `customer`: the account is a customer, default value. * - `partner`: the account is a partner. * @example customer * @enum {string|null} */ account_type?: "customer" | "partner" | null; /** * @description The type of the customer. It can have one of the following values: * - `company`: the customer is a company. * - `individual`: the customer is an individual. * @enum {string|null} */ customer_type?: "company" | "individual" | null; /** * @description The phone number of the customer * @example 1-171-883-3711 x245 */ phone?: string | null; /** * @description The state of the customer's billing address * @example CA */ state?: string | null; tax_codes?: components["schemas"]["TaxCodes"]; /** * @description The tax identification number of the customer * @example EU123456789 */ tax_identification_number?: string | null; /** @description The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone */ timezone?: components["schemas"]["TimezoneOrNull"]; /** * @description The custom website URL of the customer * @example http://hooli.com */ url?: string | null; /** * @description The zipcode of the customer's billing address * @example 91364 */ zipcode?: string | null; /** * @description The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized. * @example 30 */ net_payment_term?: number | null; /** * @description Specifies how invoices with a zero total amount should be handled: * - `inherit`: (Default) Follows the organization-level configuration. * - `finalize`: Invoices are issued and finalized even if the total amount is zero. * - `skip`: Invoices with a total amount of zero are not finalized. * @example inherit * @enum {string} */ finalize_zero_amount_invoice?: "inherit" | "skip" | "finalize"; billing_configuration?: components["schemas"]["CustomerBillingConfiguration"]; shipping_address?: components["schemas"]["Address"]; integration_customers?: { /** * Format: uuid * @description A unique identifier for the integration customer object in the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id?: string; /** * @description The integration type used for accounting and tax syncs. * Accepted values: `anrok`. * @example anrok * @enum {string} */ integration_type?: "anrok"; /** * @description Unique code used to identify an integration connection. * @example anrok1 */ integration_code?: string; /** * @description The customer ID within the integration's system. If this field is not provided, Nozle has the option to create a new customer record within the integration's system on behalf of the customer. * @example cus_12345 */ external_customer_id?: string; /** * @description Set this field to `true` if you want to create a customer record in the integration's system. This option is applicable only when the `external_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false` * @example true */ sync_with_provider?: boolean; }[]; /** @description Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format */ metadata?: { /** * Format: uuid * @description Identifier for the metadata object, only required when updating a key-value pair * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id?: string; /** * @description The metadata object key * @example Purchase Order */ key: string; /** * @description The metadata object value * @example 123456789 */ value: string; /** * @description Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice. * @example true */ display_in_invoice: boolean; }[]; /** * @description Set to `true` to exclude all invoice custom sections from PDF generation for this customer only. False by default * @example false */ skip_invoice_custom_sections?: boolean; /** * @description List of unique codes identifying the invoice custom sections. * @example [ * "eu_bank_details" * ] */ invoice_custom_section_codes?: string[]; }; }; Customer: { customer: components["schemas"]["CustomerObjectExtended"]; }; InvoiceBaseObject: { /** * Format: uuid * @description Unique identifier assigned to the fee within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the fee's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The unique code of the billing entity associated with the invoice * @example acme_corp */ billing_entity_code: string | null; /** * @description This ID helps in uniquely identifying and organizing the invoices associated with a specific customer. It provides a sequential numbering system specific to the customer, allowing for easy tracking and management of invoices within the customer's context. * @example 2 */ sequential_id?: number | null; /** * @description The unique number assigned to the invoice. This number serves as a distinct identifier for the invoice and helps in differentiating it from other invoices in the system. * @example LAG-1234-001-002 */ number: string; /** * Format: date * @description The date when the invoice was issued. It is provided in the ISO 8601 date format. * @example 2022-04-30 */ issuing_date: string; /** * Format: date-time * @description The date when the payment dispute was lost. It is expressed in Coordinated Universal Time (UTC). * @example 2022-09-14T16:35:31Z */ payment_dispute_lost_at?: string | null; /** * Format: date * @description The payment due date for the invoice, specified in the ISO 8601 date format. * @example 2022-04-30 */ payment_due_date?: string; /** * @description Specifies if the payment is considered as overdue. * @example true */ payment_overdue?: boolean; /** * @description The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized. * @example 30 */ net_payment_term?: number; /** * @description The type of invoice issued. Possible values are `subscription`, `one-off`, `credit` or `progressive_billing`. * @example subscription * @enum {string} */ invoice_type: "subscription" | "add_on" | "credit" | "one_off" | "progressive_billing"; /** * @description The status of the invoice. It indicates the current state of the invoice and can have following values: * - `draft`: the invoice is in the draft state, waiting for the end of the grace period to be finalized. During this period, events can still be ingested and added to the invoice. * - `finalized`: the invoice has been issued and finalized. In this state, events cannot be ingested or added to the invoice anymore. * - `voided`: the invoice has been issued and subsequently voided. In this state, events cannot be ingested or added to the invoice anymore. * - `pending`: the invoice remains pending until the taxes are fetched from the external provider. * - `failed`: during an attempt of finalization of the invoice, an error happened. This invoice will have an array of error_details, explaining, in which part of the system an error happened and how it's possible to fix it. This invoice can't be edited or updated, only retried. This action will discard current error_details and will create new ones if the finalization failed again. * @example finalized * @enum {string} */ status: "draft" | "finalized" | "voided" | "failed" | "pending"; /** * @description The status of the payment associated with the invoice. It can have one of the following values: * - `pending`: the payment is pending, waiting for payment processing in Stripe or when the invoice is emitted but users have not updated the payment status through the endpoint. * - `succeeded`: the payment of the invoice has been successfully processed. * - `failed`: the payment of the invoice has failed or encountered an error during processing. * @example succeeded * @enum {string} */ payment_status: "pending" | "succeeded" | "failed"; /** * @description The currency of the invoice issued. * @example EUR */ currency: components["schemas"]["Currency"]; /** * @description The total sum of fees amount in cents. It calculates the cumulative amount of all the fees associated with the invoice, providing a consolidated value. * @example 100 */ fees_amount_cents: number; /** * @description The total sum of all coupons discounted on the invoice. It calculates the cumulative discount amount applied by coupons, expressed in cents. * @example 10 */ coupons_amount_cents: number; /** * @description The total sum of all credit notes discounted on the invoice. It calculates the cumulative discount amount applied by credit notes, expressed in cents. * @example 10 */ credit_notes_amount_cents: number; /** * @description Subtotal amount, excluding taxes, expressed in cents. * This field depends on the version number. Here are the definitions based on the version: * - Version 1: is equal to the sum of `fees_amount_cents`, minus `coupons_amount_cents`, and minus `prepaid_credit_amount_cents`. * - Version 2: is equal to the `fees_amount_cents`. * - Version 3 & 4: is equal to the `fees_amount_cents`, minus `coupons_amount_cents` * @example 100 */ sub_total_excluding_taxes_amount_cents: number; /** * @description The sum of tax amount associated with the invoice, expressed in cents. * @example 20 */ taxes_amount_cents: number; /** * @description Subtotal amount, including taxes, expressed in cents. * This field depends on the version number. Here are the definitions based on the version: * - Version 1: is equal to the `total_amount_cents`. * - Version 2: is equal to the sum of `fees_amount_cents` and `taxes_amount_cents`. * - Version 3 & 4: is equal to the sum `sub_total_excluding_taxes_amount_cents` and `taxes_amount_cents` * @example 120 */ sub_total_including_taxes_amount_cents: number; /** * @description The total sum of all prepaid credits discounted on the invoice. It calculates the cumulative discount amount applied by prepaid credits, expressed in cents. * @example 0 */ prepaid_credit_amount_cents: number; /** * @description The portion of prepaid credits discounted on the invoice that originated from granted (free) credits, expressed in cents. Only populated for invoices associated with traceable wallets. * @example 0 */ prepaid_granted_credit_amount_cents?: number | null; /** * @description The portion of prepaid credits discounted on the invoice that originated from purchased (paid) credits, expressed in cents. Only populated for invoices associated with traceable wallets. * @example 0 */ prepaid_purchased_credit_amount_cents?: number | null; /** * @description The usage already billed in previous invoices. Only apply to `progressive_billing` and `subscription` invoices. * @example 0 */ progressive_billing_credit_amount_cents: number; /** * @description The sum of the amount and taxes amount on the invoice, expressed in cents. It calculates the total financial value of the invoice, including both the original amount and any applicable taxes. * @example 100 */ total_amount_cents: number; /** @example 3 */ version_number: number; /** * @description Indicates if the invoice is self-billed. Self-billing is a process where an organization creates the invoice on behalf of the partner. This field specifies whether the invoice is self-billed or not. * @example false */ self_billed?: boolean; /** * Format: uri * @description Contains the URL that provides direct access to the invoice PDF file. You can use this URL to download or view the PDF document of the invoice * @example https://billing.example.com/invoices/example.pdf */ file_url?: string | null; /** * Format: date-time * @description The date of the invoice creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the invoice object was created * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description The date of the invoice update, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The update_date provides a standardized and internationally recognized timestamp for when the invoice object was updated * @example 2022-04-29T08:59:51Z */ updated_at: string; /** @description What is still owed on the invoice, in cents. After a lost payment dispute (Core 11.45.0), it is what is owed again: what the disputes took back, plus anything still due before, less payments recorded since and offset credit notes, and never below 0. */ total_due_amount_cents?: number; /** @description What was paid on the invoice, in cents. It stays gross after a lost dispute, so after a recovery payment it can be higher than `total_amount_cents`. */ total_paid_amount_cents?: number; /** * @description What lost payment disputes took back from the invoice's payments, in cents. `0` without a lost dispute. Core 11.45.0; absent on older Cores. * @example 0 */ disputed_amount_cents?: number; total_offsetted_credit_note_amount_cents?: number; /** * @description Core 11.16.0. The amount due of this invoice carried to the customer's next invoice because it was below the payment provider's minimum charge (Stripe's minimum per currency, Razorpay INR 1). `0` when nothing was carried. A carried invoice is settled (`payment_status` `succeeded`, `total_due_amount_cents` `0`) and is never charged or dunned. See [Amounts below the provider minimum](/guides/billing/invoices#amounts-below-the-provider-minimum). * @example 0 */ carried_forward_amount_cents?: number; /** * Format: uuid * @description Core 11.16.0. The invoice that took the carried amount. `null` until the customer's next invoice in the same currency is finalized, and when nothing was carried. * @example null */ carried_forward_invoice_id?: string | null; /** * @description Core 11.16.0. The amounts of earlier invoices carried into this one, added to its total after taxes (the earlier invoices already charged their taxes). `0` when none. * @example 0 */ carried_in_amount_cents?: number; /** @description Core 11.16.0. The earlier invoices whose amounts were carried into this one. The PDF shows a line `Balance carried forward from invoice ` for each. */ carried_in_invoices?: { /** * Format: uuid * @description The earlier invoice. */ nozle_id: string; /** * @description Its number. * @example ACME-47DD-012-001 */ number: string; /** * @description The amount carried from it (its `carried_forward_amount_cents`). * @example 30 */ amount_cents: number; }[]; xml_url?: string | null; voided_at?: string | null; }; InvoiceMetadataObject: { /** * Format: uuid * @description Unique identifier assigned to the invoice metadata within the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id?: string; /** * @description Represents the key of the metadata's key-value pair. * @example digital_ref_id */ key?: string; /** * @description Represents the value of the metadata's key-value pair. * @example INV-0123456-98765 */ value?: string; /** * Format: date-time * @description The date and time when the metadata object was created. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ created_at?: string; }; InvoiceAppliedTaxObject: { /** * Format: uuid * @description Unique identifier of the invoice, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id?: string; /** * @description Fees total amount on which the tax is applied * @example 20000 */ fees_amount_cents?: number; } & components["schemas"]["BaseAppliedTax"]; InvoiceAppliedInvoiceCustomSectionObject: { /** * Format: uuid * @description Unique identifier of the applied invoice custom section in the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the invoice this custom section is applied to. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string; /** * @description Unique code identifying the invoice custom section. * @example eu_bank_details */ code: string; /** * @description The value shown on the invoice PDF. * @example Bank Name: Nozle Bank, IBAN: FR7630004000031234567890143 */ details: string; /** * @description The name of the invoice custom section displayed on the invoice. * @example Bank Details: */ display_name: string; /** * Format: date-time * @description The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2023-07-06T14:35:58Z */ created_at: string; }; UsageThresholdObject: { /** * Format: uuid * @description Unique identifier of the usage threshold created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The display name of the usage threshold. * @example Threshold 1 */ threshold_display_name: string | null; /** * @description The amount to reach to trigger a `progressive_billing` invoice. * @example 10000 */ amount_cents: number; /** * @description This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount. * @example true */ recurring: boolean; /** * Format: date-time * @description The date and time when the usage threshold was created. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2023-06-27T19:43:42Z */ created_at: string; /** * Format: date-time * @description The date and time when the usage threshold was last updated. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2023-06-27T19:43:42Z */ updated_at: string; }; AppliedUsageThresholdObject: { /** * @description The amount of usage in cents that has been accumulated over the lifetime of the subscription. * @example 2000 */ lifetime_usage_amount_cents: number; /** * Format: date-time * @description The date and time when the lifetime usage was computed. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2025-03-31T12:31:44Z */ created_at: string; usage_threshold: components["schemas"]["UsageThresholdObject"]; }; InvoiceObject: components["schemas"]["InvoiceBaseObject"] & { /** @description The customer on which the invoice applies. It refers to the customer account or entity associated with the invoice. */ customer?: components["schemas"]["CustomerObject"]; metadata?: components["schemas"]["InvoiceMetadataObject"][]; applied_taxes?: components["schemas"]["InvoiceAppliedTaxObject"][]; /** @description The invoice custom sections applied to this invoice for PDF generation. */ applied_invoice_custom_sections?: components["schemas"]["InvoiceAppliedInvoiceCustomSectionObject"][]; applied_usage_thresholds?: components["schemas"]["AppliedUsageThresholdObject"][]; }; InvoicesPaginated: { invoices: components["schemas"]["InvoiceObject"][]; meta: components["schemas"]["PaginationMeta"]; }; /** @description The payment plus when Nozle will debit it automatically and with which kind of payment method. */ PaymentScheduledObject: components["schemas"]["PaymentObject"] & { /** * Format: date-time * @description When the automatic debit is planned, ISO 8601 in UTC. * @example 2026-10-30T14:30:00Z */ scheduled_at: string; /** * @description The kind of saved payment method that will be debited. * @example card * @enum {string} */ method_type: "card" | "upi" | "bank"; }; /** @description The payment plus the announced debit time and why the debit will not happen. There is no `method_type`. */ PaymentScheduleCancelledObject: components["schemas"]["PaymentObject"] & { /** * Format: date-time * @description The debit time that was announced, ISO 8601 in UTC. * @example 2026-10-30T14:30:00Z */ scheduled_at: string; /** * @description Why the debit was cancelled. `mandate_changed`, the card or mandate can no longer be used or changed; `invoice_paid`, the invoice was paid another way while the debit waited; `invoice_voided`, the invoice was voided while the debit waited; `notice_failed`, the bank or provider notice failed; `other`, any other failed check before the debit, for example a changed amount. * @example invoice_paid * @enum {string} */ reason: "mandate_changed" | "invoice_paid" | "invoice_voided" | "notice_failed" | "other"; }; PaymentObject: { /** * Format: uuid * @description The unique identifier of the payment, created by Nozle. * @example 4cf085a7-c196-4f07-a543-97c50ec6e8b2 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the customer, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** @description List of invoice IDs associated with the payment. */ invoice_ids: string[]; /** @description List of invoice numbers associated with the payment. */ invoice_numbers?: string[]; /** * Format: uuid * @description The unique identifier of the paid resource, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ payable_id: string; /** * @description The type of the paid resource, associated with the `payable_id`. * @example Invoice * @enum {string} */ payable_type: "Invoice" | "PaymentRequest"; /** * @description The amount of the payment in cents. * @example 1099 */ amount_cents: number; /** * @description The currency of the payment amount. * @example USD */ amount_currency: components["schemas"]["Currency"]; /** * @description The status of the payment within the payment provider. This can be very different from a payment provider to another. * @example Completed */ status: string; /** * @description The normalized payment status by Nozle. * @example succeeded * @enum {string} */ payment_status: "succeeded" | "failed" | "pending" | "processing"; /** * @description The type of payment. * @example manual * @enum {string} */ type: "manual" | "provider"; /** * @description Reference for the payment. * @example ref1 */ reference: string | null; /** * @description Code of the payment provider * @example stripe_prod */ payment_provider_code: string; /** * @description The type of payment provider * @example stripe * @enum {string} */ payment_provider_type: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash"; /** @description DEPRECATED: use provider_payment_id */ external_payment_id: string | null; /** * @description Unique identifier of the payment within the payment provider (if applicable). * @example pi_5eb0285741bc6ba */ provider_payment_id: string | null; /** * @description Unique identifier of the customer within the payment provider * @example cus_5eb0285bcf941bc6ba */ provider_customer_id: string; /** * Format: uuid * @description The unique identifier of the payment method used for this payment. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ payment_method_id?: string | null; /** * @description The next action to be taken by the customer to complete the payment. Should usually be empty, except when receiving the `payment.requires_action` webhook. * @example { * "type": "redirect_to_url", * "redirect_to_url": { * "url": "https://hooks.stripe.com/3d_secure_2/hosted?merchant=acct_AAA&payment_intent=pi_BBB&payment_intent_client_secret=pi_BBB&publishable_key=pk_test_CCC", * "return_url": "https://app.example.com" * } * } */ next_action: { [key: string]: unknown; }; /** * Format: date-time * @description Timestamp when the payment was created in Nozle's database, not on the payment provider. * @example 2025-01-21T00:10:29Z */ created_at: string; }; PaymentsPaginated: { payments: components["schemas"]["PaymentObject"][]; meta: components["schemas"]["PaginationMeta"]; }; PaymentRequestObject: { /** * Format: uuid * @description Unique identifier of the payment request, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: email * @description The customer's email address used for sending dunning notifications * @example dinesh@piedpiper.test */ email: string; /** * @description The sum of the total amounts of all the invoices included in the payment request, expressed in cents. * @example 100 */ amount_cents: number; /** * @description The currency of the payment request. * @example EUR */ amount_currency: components["schemas"]["Currency"]; /** * @description The status of the payment associated with the payment request. It can have one of the following values: * - `pending`: the payment is pending, waiting for payment processing in the payment provider or when the invoice is emitted but users have not updated the payment status through the endpoint. * - `succeeded`: the payment of the payment request has been successfully processed. * - `failed`: the payment of the payment request has failed or encountered an error during processing. * @example succeeded * @enum {string} */ payment_status: "pending" | "succeeded" | "failed"; /** * Format: date-time * @description The date and time when the payment request was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the payment request was initially created. * @example 2022-04-29T08:59:51Z */ created_at: string; /** @description The customer on which the payment request applies. It refers to the customer account or entity associated with the payment request. */ customer: components["schemas"]["CustomerBaseObject"]; invoices: components["schemas"]["InvoiceBaseObject"][]; /** * @description `true` when Core created the request itself for an invoice it did not charge (a Razorpay customer without a mandate, or a Stripe customer without a usable saved payment method), `false` for a request created by dunning or by hand. * @example false */ automatic?: boolean; }; PaymentRequestsPaginated: { payment_requests: components["schemas"]["PaymentRequestObject"][]; meta: components["schemas"]["PaginationMeta"]; }; AppliedInvoiceCustomSectionObject: { /** * Format: uuid * @description Unique identifier of the applied invoice custom section in the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: date-time * @description The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2023-07-06T14:35:58Z */ created_at: string; /** * Format: uuid * @deprecated * @description Unique identifier of the invoice custom section that was applied. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_custom_section_id?: string; invoice_custom_section: components["schemas"]["InvoiceCustomSectionObject"]; }; /** @description Reference to a specific payment method for processing the payment. */ PaymentMethodReference: { /** * @description The type of payment method to use. * @example provider * @enum {string} */ payment_method_type?: "provider" | "manual"; /** * Format: uuid * @description The unique identifier of the payment method (required when using a specific provider payment method). * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ payment_method_id?: string | null; }; SubscriptionActivationRuleObject: { /** * Format: uuid * @description Unique identifier assigned to the activation rule within the Nozle application. This ID is exclusively created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The type of the activation rule. Only `payment` is currently supported. A `payment` rule gates the subscription activation on a successful payment of the first invoice. * @example payment * @enum {string} */ type: "payment"; /** * @description The number of hours the subscription stays in the `incomplete` state waiting for the payment to succeed before it is automatically canceled. * @example 48 */ timeout_hours: number; /** * @description The evaluation status of the activation rule: * - `inactive`: the rule has not been evaluated yet. * - `pending`: the rule is applicable and is waiting to be satisfied (e.g. waiting for the payment). * - `satisfied`: the rule has been satisfied and no longer blocks activation. * - `declined`: the rule was applicable but was declined. * - `failed`: the rule could not be satisfied (e.g. the payment failed). * - `expired`: the rule was not satisfied before its timeout elapsed. * - `not_applicable`: the rule did not apply to this subscription. * @example pending * @enum {string} */ status: "inactive" | "pending" | "satisfied" | "declined" | "failed" | "expired" | "not_applicable"; /** * Format: date-time * @description The date and time when the rule expires, after which an unsatisfied rule causes the subscription to be canceled. Represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Null until the rule starts being evaluated. * @example 2022-08-10T00:00:00Z */ expires_at?: string | null; /** * Format: date-time * @description The creation date of the activation rule, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ created_at: string; /** * Format: date-time * @description The last update date of the activation rule, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ updated_at: string; }; SubscriptionObject: { /** * Format: uuid * @description Unique identifier assigned to the subscription within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the subscription's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The subscription external unique identifier (provided by your own application). * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_id: string; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application). * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The code of the billing entity associated with the subscription. * @example default */ billing_entity_code?: string; /** * @description The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration). * @example anniversary * @enum {string} */ billing_time: "calendar" | "anniversary"; /** * @description The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan. * @example Repository A */ name: string | null; /** * @description The unique code representing the plan to be attached to the customer. This code must correspond to the `code` property of one of the active plans. * @example premium */ plan_code: string; /** * @description The version of the plan code the subscription is billed on. A subscription stays on its version when the plan's pricing changes, until a version migration moves it. * @example 1 */ plan_version?: number | null; /** * @description The version of the subscription this one replaced, when it replaced one (for example after a version migration). * @example null */ previous_plan_version?: number | null; /** * @description The version the subscription moves to at the end of its period, when a change or a version migration is scheduled. * @example 2 */ next_plan_version?: number | null; /** * Format: uuid * @description The version migration that started this subscription, when one did. * @example null */ plan_version_migration_id?: string | null; /** * @description The base cost of the related plan, excluding any applicable taxes, that is billed on a recurring basis. * @example 10000 */ plan_amount_cents?: number; /** * @description The currency of the related plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. * @example USD */ plan_amount_currency?: components["schemas"]["Currency"]; /** * @description The status of the subscription, which can have the following values: * - `active`: the subscription is currently active and applied to the customer. * - `canceled`: the subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer, when a subscription with a pending status is terminated, or when a payment-gated subscription fails to be paid (or its activation rule expires) before activation. When caused by payment gating, the `cancellation_reason` field is set. * - `incomplete`: the subscription was created with a payment activation rule and is waiting for the gating payment to succeed before it becomes `active`. It is automatically `canceled` if the payment fails or the activation rule expires. * - `pending`: a previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period. * - `terminated`: the subscription is no longer active. * @example active * @enum {string} */ status: "active" | "canceled" | "incomplete" | "pending" | "terminated"; /** * Format: date-time * @description The creation date of the subscription, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). This date provides a timestamp indicating when the subscription was initially created. * @example 2022-08-08T00:00:00Z */ created_at: string; /** * Format: date-time * @description The cancellation date of the subscription. This field is not null when the subscription is `canceled`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-09-14T16:35:31Z */ canceled_at: string | null; /** * Format: date-time * @description The effective start date of the subscription. This field can be null if the subscription is `pending` or `canceled`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ started_at: string | null; /** * Format: date-time * @description The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC). * @example 2022-10-08T00:00:00Z */ ending_at: string | null; /** * Format: date-time * @description The anniversary date and time of the initial subscription. This date serves as the basis for billing subscriptions with `anniversary` billing time. The `anniversary_date` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ subscription_at: string; /** * Format: date-time * @description The termination date of the subscription. This field is not null when the subscription is `terminated`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC) * @example 2022-09-14T16:35:31Z */ terminated_at: string | null; /** * @description The code identifying the previous plan associated with this subscription. * @example null */ previous_plan_code: string | null; /** * @description The code identifying the next plan in the case of a downgrade. * @example null */ next_plan_code: string | null; /** * Format: date * @description The date when the plan will be downgraded, represented in ISO 8601 date format. * @example 2022-04-30 */ downgrade_plan_date: string | null; /** * Format: date-time * @description The date when the free trial is ended, represented in ISO 8601 date format. * @example 2022-08-08T00:00:00Z */ trial_ended_at: string | null; /** * Format: date-time * @description The date and time when the current billing period started, represented in ISO 8601 date format. * @example 2022-08-08T00:00:00Z */ current_billing_period_started_at: string | null; /** * Format: date-time * @description The date and time when the current billing period ends, represented in ISO 8601 date format. * @example 2022-09-08T00:00:00Z */ current_billing_period_ending_at: string | null; /** * @description When a pay-in-advance subscription is terminated before the end of its billing period, we generate a credit note for the unused subscription time by default. * This field allows you to control the behavior of the credit note generation: * * - `credit`: A credit note is generated for the unused subscription time. The unused amount is credited back to the customer. * - `refund`: A credit note is generated for the unused subscription time. If the invoice is paid or partially paid, the unused paid amount is refunded; any unpaid unused amount is credited back to the customer. * - `offset`: A credit note is generated for the unused subscription time. If the invoice is paid or partially paid, the unused paid amount is refunded; any unpaid unused amount is applied to the invoice reducing its amount due. * - `skip`: No credit note is generated for the unused subscription time. * * _Note: This field is only applicable to pay-in-advance plans and will be `null` for pay-in-arrears plans._ * @example credit * @enum {string|null} */ on_termination_credit_note: "credit" | "refund" | "offset" | "skip" | null; /** * @description When a subscription is terminated before the end of its billing period, we generate an invoice for the unbilled usage. * This field allows you to control the behavior of the invoice generation: * * - `generate`: An invoice is generated for the unbilled usage. * - `skip`: No invoice is generated for the unbilled usage. * @default generate * @example generate * @enum {string} */ on_termination_invoice: "generate" | "skip"; /** @description The invoice custom sections applied to invoices generated by this subscription. */ applied_invoice_custom_sections?: components["schemas"]["AppliedInvoiceCustomSectionObject"][]; /** @description The payment method assigned to this subscription for processing payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; /** * @description Controls whether this subscription is eligible to be grouped with other subscriptions of the same customer on a consolidated recurring invoice. * * - `true` (default): the subscription is included in the customer's standard invoice grouping (by billing entity, currency and payment method). * - `false`: the subscription is excluded from consolidation and always billed on its own dedicated invoice, regardless of other grouping criteria. * @default true * @example true */ consolidate_invoice: boolean; /** * @description The reason a payment-gated subscription was canceled before activation. Null unless the subscription was canceled by payment gating. * * - `payment_failed`: the gating payment failed. * - `timeout`: the activation rule expired before the payment succeeded. * @example payment_failed * @enum {string|null} */ cancellation_reason?: "payment_failed" | "timeout" | null; /** * Format: date-time * @description The date and time when a payment-gated subscription was activated (i.e. moved from `incomplete` to `active` once the gating payment succeeded), represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Null while the subscription is still `incomplete`. * @example 2022-08-08T00:00:00Z */ activated_at?: string | null; /** @description The activation rules attached to the subscription. A payment activation rule gates activation on a successful first payment, keeping the subscription in the `incomplete` state until the payment succeeds or the rule expires. */ activation_rules?: components["schemas"]["SubscriptionActivationRuleObject"][]; billing_authority?: string; credit_import_completed_at?: string | null; progressive_billing_disabled?: boolean; purchase_order_number?: string | null; }; SubscriptionsPaginated: { subscriptions: components["schemas"]["SubscriptionObject"][]; meta: components["schemas"]["PaginationMeta"]; }; /** @description Object that represents rule for wallet recurring transactions. */ WalletRecurringTransactionRule: { /** * Format: uuid * @description A unique identifier for the recurring transaction rule in the Nozle application. Can be used to update a recurring transaction rule. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The trigger. Possible values are `interval` or `threshold`. * @example interval * @enum {string} */ trigger: "interval" | "threshold"; /** * @description The method used for recurring top-up. Possible values are `fixed` or `target`. * @example target * @enum {string} */ method: "fixed" | "target"; /** * @description The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly`, `semiannual` or `yearly`. Required only if trigger is set to `interval`. * @example monthly * @enum {string} */ interval: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description The status of the recurring transaction rule. Possible values are `active` or `terminated`. * @example active * @enum {string} */ status: "active" | "terminated"; /** * @description The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`. * @example 20.0 */ threshold_credits: string; /** * @description The number of paid credits. Required only if there is no granted credits. * @example 20.0 */ paid_credits: string; /** * @description The number of free granted credits. Required only if there is no paid credits. * @example 10.0 */ granted_credits: string; /** * @description Applies only to `target` rules. When `true`, the recurring top-up grants free credits to reach the target ongoing balance instead of creating a paid top-up (and bypasses the paid top-up minimum). When `false`, the gap is filled with a paid top-up. `null` for `fixed` rules. Defaults to `false` for target rules when omitted. * @example false */ grants_target_top_up: boolean | null; /** * Format: date-time * @description The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ started_at: string | null; /** * @description The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`. * @example 200.0 */ target_ongoing_balance: string | null; /** * Format: date-time * @description The date of the metadata object creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the metadata object was created * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2023-09-30T23:59:59Z */ expiration_at: string | null; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment: boolean; /** * @description This field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule. * @example [ * { * "key": "example_key", * "value": "example_value" * }, * { * "key": "another_key", * "value": "another_value" * } * ] */ transaction_metadata: { /** @description The unique identifier for the attribute. */ key?: string; /** @description The value associated with the key. */ value?: string; }[]; /** * @description The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. * @example Tokens for models 'high-fidelity-boost' */ transaction_name: string | null; /** * @description When true, allows rule to topped up wallet with transactions that exceed the paid top-up limits. Defaults to false. * @example false */ ignore_paid_top_up_limits: boolean; /** @description The invoice custom sections applied to invoices generated by this recurring transaction rule. */ applied_invoice_custom_sections?: components["schemas"]["AppliedInvoiceCustomSectionObject"][]; /** @description The payment method assigned to this recurring transaction rule for processing top-up payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; }; WalletObject: { /** * Format: uuid * @description Unique identifier assigned to the wallet within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the wallet's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example hooli_1234 */ external_customer_id: string; /** * @description The code of the billing entity associated with the wallet. * @example default */ billing_entity_code?: string; /** * @description The status of the wallet. Possible values are `active` or `terminated`. * @example active * @enum {string} */ status: "active" | "terminated"; /** * @description The currency of the wallet. * @example USD */ currency: components["schemas"]["Currency"]; /** * @description The name of the wallet. * @example Prepaid */ name?: string | null; /** * @description The code of the wallet. * @example prepaid */ code?: string | null; /** * @description Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50. * @example 50 */ priority?: number; /** * @description The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction. * @example 1.5 */ rate_amount: string; /** * @description The current wallet balance expressed in credits. This reflects the available balance after all transactions are settled. * @example 28.0 */ credits_balance: string; /** * @description The current wallet balance expressed in cents. This reflects the available balance after all transactions are settled. * @example 1000 */ balance_cents: number; /** * @description The number of consumed credits. * @example 2.0 */ consumed_credits: string; /** * Format: date-time * @description The date of the wallet creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example null */ expiration_at?: string | null; /** * Format: date-time * @description The date and time of the last balance top-up. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ last_balance_sync_at?: string | null; /** * Format: date-time * @description The date and time of the last credits consumption. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ last_consumed_credit_at?: string | null; /** * Format: date-time * @description The date of terminaison of the wallet. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2022-09-14T16:35:31Z */ terminated_at?: string | null; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment: boolean; /** @description Set wallet limitations to fee types. */ applies_to?: { /** * @description An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only. * @example [ * "charge" * ] */ fee_types?: ("charge" | "subscription" | "commitment")[]; /** * @description An array of feature codes to which the wallet is applicable. By specifying the feature codes in this field, you can restrict the wallet's usage to specific metrics only. * @example [ * "bm1" * ] */ feature_codes?: string[]; }; /** @description List of recurring transaction rules. Currently, we only allow one recurring rule per wallet. */ recurring_transaction_rules?: components["schemas"]["WalletRecurringTransactionRule"][]; /** * @description The ongoing wallet balance expressed in cents. This represents the `balance_cents` minus the `ongoing_usage_balance_cents`, showing the real time balance after accounting for current usage including taxes. * @example 800 */ ongoing_balance_cents: number; /** * @description The ongoing usage balance of the wallet, expressed in cents. This reflects all current usage and draft invoices including taxes. * @example 200 */ ongoing_usage_balance_cents: number; /** * @description The ongoing wallet balance expressed in credits. This represents the `credits_balance` minus the `credits_ongoing_usage_balance`, showing the real time balance after accounting for current usage including taxes. * @example 8.0 */ credits_ongoing_balance: string; /** * @description The ongoing usage balance of the wallet, expressed in credits. This reflects all current usage and draft invoices including taxes. * @example 2.0 */ credits_ongoing_usage_balance: string; /** * @description Minimum amount of cents that can be top-up with a single paid transaction. * @example 100 */ paid_top_up_min_amount_cents?: number | null; /** * @description Maximum amount of cents that can be top-up with a single paid transaction. * @example 1000 */ paid_top_up_max_amount_cents?: number | null; /** @description The invoice custom sections applied to invoices generated by this wallet. */ applied_invoice_custom_sections?: components["schemas"]["AppliedInvoiceCustomSectionObject"][]; /** @description The payment method assigned to this wallet for processing top-up payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; metadata?: components["schemas"]["MetadataObject"]; }; WalletsPaginated: { wallets: components["schemas"]["WalletObject"][]; meta: components["schemas"]["PaginationMeta"]; }; /** @description Configuration for invoice custom sections to apply to invoices generated by this resource. */ InvoiceCustomSectionInput: { /** * @description Set to `true` to exclude all invoice custom sections from PDF generation for invoices related to this resource. When `true`, `invoice_custom_section_codes` is ignored. * @example false */ skip_invoice_custom_sections?: boolean; /** * @description List of unique codes identifying the invoice custom sections to apply. These override the default invoice custom sections configured at the customer or billing entity level. * @example [ * "eu_bank_details" * ] */ invoice_custom_section_codes?: string[]; }; WalletCreateInput: { wallet?: { /** * @description The name of the wallet. * @example Prepaid */ name?: string | null; /** * @description The code of the wallet. * @example prepaid */ code?: string | null; /** * @description Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50. * @example 50 */ priority?: number; /** * @description The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction. * @example 1.5 */ rate_amount: string; /** * @description The currency of the wallet. * @example USD */ currency: components["schemas"]["Currency"]; /** * @description The number of paid credits. Required only if there is no granted credits. * @example 20.0 */ paid_credits?: string | null; /** * @description The number of free granted credits. Required only if there is no paid credits. * @example 10.0 */ granted_credits?: string | null; /** * @description The customer external unique identifier (provided by your own application) * @example hooli_1234 */ external_customer_id: string; /** * @description The code of the billing entity associated with the wallet. If not provided, the customer's billing entity is used. * @example default */ billing_entity_code?: string; /** * Format: date-time * @description The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2022-07-07T23:59:59Z */ expiration_at?: string | null; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment?: boolean; /** * @description This optional field allows you to store a list of key-value pairs that provide additional information or custom attributes. These key-value pairs will be included in the metadata of wallet transactions generated during the wallet creation process. * @example [ * { * "key": "example_key", * "value": "example_value" * }, * { * "key": "another_key", * "value": "another_value" * } * ] */ transaction_metadata?: { /** @description The unique identifier for the attribute. */ key?: string; /** @description The corresponding value for the key. */ value?: string; }[] | null; /** * @description The name of the wallet transactions triggered when creating the wallet. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. * @example Tokens for models 'high-fidelity-boost' */ transaction_name?: string | null; /** @description Set wallet limitations to fee types. */ applies_to?: { /** * @description An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only. * @example [ * "charge" * ] */ fee_types?: ("charge" | "subscription" | "commitment")[] | null; /** * @description An array of feature codes to which the wallet is applicable. By specifying the feature codes in this field, you can restrict the wallet's usage to specific metrics only. * @example [] */ feature_codes?: string[] | null; } | null; /** * @description Minimum amount of cents that can be top-up with a single paid transaction. * @example 100 */ paid_top_up_min_amount_cents?: number | null; /** * @description Maximum amount of cents that can be top-up with a single paid transaction. * @example 1000 */ paid_top_up_max_amount_cents?: number | null; /** * @description If set to true, the wallet will ignore paid top-up limits on creation. * @example false */ ignore_paid_top_up_limits_on_creation?: boolean | null; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description List of recurring transaction rules. Currently, we only allow one recurring rule per wallet. */ recurring_transaction_rules?: { /** * @description The number of paid credits used for recurring top-up. * @example 20.0 */ paid_credits?: string | null; /** * @description The number of free granted credits used for recurring top-up. * @example 10.0 */ granted_credits?: string | null; /** * @description Applies only to `target` rules. When `true`, the recurring top-up grants free credits up to the target ongoing balance exactly instead of creating a paid top-up, and the paid top-up minimum does not apply. When `false`, the gap is filled with a paid top-up. Accepted values are `true`, `false`, `"true"`, `"false"` and `null`. `true` on a rule whose `method` is not `target` returns `422 invalid_recurring_rule`; send `method: target` with it. A new target rule defaults to `false`; on update, leaving it out keeps the stored value, and changing a rule to `fixed` clears it. Accepted by `POST /wallets`, `PUT /wallets/{id}` and the customer-scoped wallet endpoints, and returned on every rule. * @example false */ grants_target_top_up?: boolean | null; /** * @description The method used for recurring top-up. Possible values are `fixed` or `target`. * @example target * @enum {string} */ method?: "fixed" | "target"; /** * @description The trigger. Possible values are `interval` or `threshold`. * @example interval * @enum {string} */ trigger: "interval" | "threshold"; /** * @description The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly`, `semiannual` or `yearly`. Required only when trigger is `interval`. * @example monthly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * Format: date-time * @description The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ started_at?: string | null; /** * Format: date-time * @description The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2023-09-30T23:59:59Z */ expiration_at?: string | null; /** * @description The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`. * @example 20.0 */ threshold_credits?: string; /** * @description The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`. * @example 200.0 */ target_ongoing_balance?: string; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment?: boolean; /** * @description This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule. * @example [ * { * "key": "example_key", * "value": "example_value" * }, * { * "key": "another_key", * "value": "another_value" * } * ] */ transaction_metadata?: { /** @description The unique identifier for the attribute. */ key?: string; /** @description The value associated with the key. */ value?: string; }[]; /** * @description The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. * @example Tokens for models 'high-fidelity-boost' */ transaction_name?: string | null; /** * @description When true, allows rule to topped up wallet with transactions that exceed the paid top-up limits. Defaults to false. * @example false */ ignore_paid_top_up_limits?: boolean; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description Optional payment method to use for processing recurring top-up payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; }[] | null; /** @description Optional payment method to use for processing wallet top-up payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; metadata?: components["schemas"]["MetadataInput"]; }; }; Wallet: { wallet: components["schemas"]["WalletObject"]; }; WalletUpdateInput: { wallet: { /** * @description The name of the wallet. * @example new_name */ name?: string | null; /** * @description The code of the wallet. * @example prepaid */ code?: string | null; /** * @description Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50. * @example 50 */ priority?: number; /** * Format: date-time * @description The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2022-07-07T23:59:59Z */ expiration_at?: string | null; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment?: boolean; /** * @description The code of the billing entity associated with the wallet. * @example default */ billing_entity_code?: string; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description List of recurring transaction rules. Currently, we only allow one recurring rule per wallet. */ recurring_transaction_rules?: { /** * Format: uuid * @description A unique identifier for the recurring transaction rule in the Nozle application. Can be used to update a recurring transaction rule. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id?: string; /** * @description The trigger. Possible values are `interval` or `threshold`. * @example interval * @enum {string} */ trigger: "interval" | "threshold"; /** * @description The method used for recurring top-up. Possible values are `fixed` or `target`. * @example target * @enum {string} */ method?: "fixed" | "target"; /** * @description The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly`, `semiannual` or `yearly`. Required only when trigger is set to `interval`. * @example monthly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`. * @example 20.0 */ threshold_credits?: string; /** * @description The number of paid credits. Required only if there is no granted credits. * @example 20.0 */ paid_credits?: string | null; /** * @description The number of free granted credits. Required only if there is no paid credits. * @example 10.0 */ granted_credits?: string | null; /** * @description Applies only to `target` rules. When `true`, the recurring top-up grants free credits up to the target ongoing balance exactly instead of creating a paid top-up, and the paid top-up minimum does not apply. When `false`, the gap is filled with a paid top-up. Accepted values are `true`, `false`, `"true"`, `"false"` and `null`. `true` on a rule whose `method` is not `target` returns `422 invalid_recurring_rule`; send `method: target` with it. A new target rule defaults to `false`; on update, leaving it out keeps the stored value, and changing a rule to `fixed` clears it. Accepted by `POST /wallets`, `PUT /wallets/{id}` and the customer-scoped wallet endpoints, and returned on every rule. * @example false */ grants_target_top_up?: boolean | null; /** * Format: date-time * @description The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ started_at?: string | null; /** * Format: date-time * @description The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). * @example 2023-09-30T23:59:59Z */ expiration_at?: string | null; /** * @description The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`. * @example 200.0 */ target_ongoing_balance?: string; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment?: boolean; /** * @description This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule. * @example [ * { * "key": "example_key", * "value": "example_value" * }, * { * "key": "another_key", * "value": "another_value" * } * ] */ transaction_metadata?: { /** @description The unique identifier for the attribute. */ key?: string; /** @description The value associated with the key. */ value?: string; }[]; /** * @description The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. * @example Tokens for models 'high-fidelity-boost' */ transaction_name?: string | null; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description Optional payment method to use for processing recurring top-up payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; }[]; /** @description Optional payment method to use for processing wallet top-up payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; /** @description Set wallet limitations to fee types. */ applies_to?: { /** * @description An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only. * @example [ * "charge" * ] */ fee_types?: ("charge" | "subscription" | "commitment")[] | null; /** * @description An array of feature codes to which the wallet is applicable. By specifying the feature codes in this field, you can restrict the wallet's usage to specific metrics only. * @example [] */ feature_codes?: string[] | null; } | null; metadata?: components["schemas"]["MetadataInput"]; }; }; WalletMetadataResponse: { metadata: components["schemas"]["MetadataObject"]; }; AlertThresholdBaseObject: { /** * @description Unique identifier of the usage threshold created by Nozle. * @example warn */ code?: string | null; /** * @description This field when set to `true` indicates that the alert will be retrigger when this threshold is reached after the last non-recurring threshold. Only one recurring threshold per alert allowed. * @default false * @example false */ recurring: boolean; }; AlertThresholdObject: components["schemas"]["AlertThresholdBaseObject"] & { /** * @description A value that should trigger this alert, formatted as a BigDecimal. * @example 99.0 */ value: string; }; WalletAlertObject: { /** * Format: uuid * @description Unique identifier of the alert, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the organization, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; external_subscription_id: null; /** * @description Unique identifier of the wallet, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ wallet_id?: string; /** * @description The wallet external unique identifier (provided by your own application). * @example wallet_code */ wallet_code?: string; feature: null; /** * @description The type of alert. * @example wallet_balance_amount * @enum {string} */ alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance"; /** * @description Unique code used to identify the alert. * @example wallet_balance_alert */ code: string; /** * @description The name of the alert. * @example Wallet Balance Alert */ name: string | null; /** * @description Indicates whether the alert is triggered when the monitored metric goes above or below the threshold. * @example decreasing * @enum {string} */ direction?: "increasing" | "decreasing"; /** * @description When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds. * @example 1000 */ previous_value: number; /** * Format: date-time * @description The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time. * @example 2025-05-19T10:04:21Z */ last_processed_at: string | null; /** @description Array of thresholds associated with the alert. */ thresholds: components["schemas"]["AlertThresholdObject"][]; /** * Format: date-time * @description The date and time in UTC (ISO 8601) when the alert was created. * @example 2025-03-20T10:00:00Z */ created_at: string; }; WalletAlerts: { alerts: components["schemas"]["WalletAlertObject"][]; meta?: components["schemas"]["PaginationMeta"]; }; AlertThresholdInput: components["schemas"]["AlertThresholdBaseObject"] & { /** * @description A value that should trigger this alert. This can be an integer or a string formatted as a BigDecimal. * @example 99 */ value: number | string; }; AlertBaseInput: { /** * @description Unique code used to identify the alert. * @example storage_threshold_alert */ code?: string; /** * @description The name of the alert. * @example Storage Usage Alert */ name?: string | null; /** @description Array of thresholds associated with the alert. */ thresholds?: components["schemas"]["AlertThresholdInput"][]; }; WalletAlertCreateInput: { alert: components["schemas"]["AlertBaseInput"] & { /** * @description The type of alert. * @example wallet_balance_amount * @enum {string} */ alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance"; /** * @description Unique code used to identify the alert. * @example wallet_balance_alert */ code: string; /** * @description The name of the alert. * @example Wallet Balance Alert */ name?: string | null; }; }; WalletAlertBatchCreateInput: { /** @description Array of alerts to create. All alerts are created atomically - if any fail validation, none are created. */ alerts: (components["schemas"]["AlertBaseInput"] & { /** * @description The type of alert. * @example wallet_balance_amount * @enum {string} */ alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance"; /** * @description Unique code used to identify the alert. * @example wallet_balance_alert */ code: string; /** * @description The name of the alert. * @example Wallet Balance Alert */ name?: string | null; })[]; }; WalletAlert: { alert: components["schemas"]["WalletAlertObject"]; }; WalletAlertUpdateInput: { alert: components["schemas"]["AlertBaseInput"] & { /** * @description Unique code used to identify the alert. * @example wallet_balance_alert */ code?: string; /** * @description The name of the alert. * @example Wallet Balance Alert */ name?: string | null; }; }; /** @description Details about the pricing unit used for charge usage. */ UsagePricingUnitDetailsObject: { /** * @description The amount in cents in the pricing unit. * @example 200 */ amount_cents: number; /** * @description The short name of the pricing unit. * @example CR */ short_name: string; /** * @description The conversion rate from pricing units to the plan's currency. * @example 0.5 */ conversion_rate: string; } | null; /** @description Array of filter object, representing multiple dimensions for a charge item. */ CustomerChargeFiltersUsageObject: { /** * @description The number of units consumed for a specific charge filter related to a charge item. * @example 0.9 */ units: string; /** * @description The total number of units consumed by the customer for a specific charge item, aggregated across all usage events. * @example 1.0 */ total_aggregated_units: string; /** * @description The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item. * @example 1000 */ amount_cents: number; /** * @description The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts. * @example 10 */ events_count: number; /** * @description Specifies the name that will be displayed on an invoice. * @example AWS eu-east-1 */ invoice_display_name?: string; pricing_unit_details?: components["schemas"]["UsagePricingUnitDetailsObject"]; /** * @description List of filter values applied to the usage. * @example { * "region": [ * "us-east-1" * ] * } */ values: { [key: string]: string[]; }; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; }[]; /** @description Array of aggregated fees, grouped by the event properties defined in a `standard` charge model. */ CustomerChargeGroupedUsageObject: { /** * @description The amount in cents, tax excluded, consumed for a specific group related to a charge item. * @example 1000 */ amount_cents: number; /** * @description The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts. * @example 10 */ events_count: number; /** * @description The number of units consumed for a specific group related to a charge item. * @example 0.9 */ units: string; /** * @description The total number of units consumed by the customer for a specific charge item, aggregated across all usage events. * @example 1.0 */ total_aggregated_units: string; pricing_unit_details?: components["schemas"]["UsagePricingUnitDetailsObject"]; /** @description Key value list of event properties aggregated by the charge model */ grouped_by: { [key: string]: string; }; filters: components["schemas"]["CustomerChargeFiltersUsageObject"]; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; }[]; CustomerChargeUsageObject: { /** * @description The number of units consumed by the customer for a specific charge item. * @example 1.0 */ units: string; /** * @description The total number of units consumed by the customer for a specific charge item, aggregated across all usage events. * @example 1.0 */ total_aggregated_units: string; /** * @description The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts. * @example 10 */ events_count: number; /** * @description The amount in cents, tax excluded, consumed by the customer for a specific charge item. * @example 123 */ amount_cents: number; /** * @description The currency of a usage item consumed by the customer. * @example EUR */ amount_currency: components["schemas"]["Currency"]; pricing_unit_details?: components["schemas"]["UsagePricingUnitDetailsObject"]; /** @description Object listing all the properties for a specific charge item. */ charge: { /** * Format: uuid * @description Unique identifier assigned to the charge within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the charge's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The pricing model applied to this charge. Possible values are standard, `graduated`, `percentage`, `package` or `volume`. * @example graduated * @enum {string} */ charge_model: "standard" | "graduated" | "package" | "percentage" | "volume"; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string | null; }; /** @description The related feature object. */ feature: { /** * Format: uuid * @description Unique identifier assigned to the feature within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the feature's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The name of the feature used for this charge. * @example Storage */ name: string; /** * @description The code of the feature used for this charge. * @example storage */ code: string; /** * @description The aggregation type of the feature used for this charge. Possible values are `count_agg`, `sum_agg`, `max_agg` or `unique_count_agg`. * @example sum_agg * @enum {string} */ aggregation_type: "count_agg" | "sum_agg" | "max_agg" | "unique_count_agg" | "weighted_sum_agg" | "latest_agg"; }; filters?: components["schemas"]["CustomerChargeFiltersUsageObject"]; grouped_usage?: components["schemas"]["CustomerChargeGroupedUsageObject"]; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; }; CustomerUsageObject: { /** * Format: date-time * @description The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC). * @example 2022-07-01T00:00:00Z */ from_datetime: string; /** * Format: date-time * @description The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC). * @example 2022-07-31T23:59:59Z */ to_datetime: string; /** * Format: date * @description The date of creation of the invoice. * @example 2022-08-01 */ issuing_date: string; /** * Format: uuid * @description A unique identifier associated with the invoice related to this particular usage record. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id?: string | null; /** * @description The currency of the customer's current usage. * @example EUR */ currency?: components["schemas"]["Currency"]; /** * @description The amount in cents, tax excluded. * @example 123 */ amount_cents: number; /** * @description The tax amount in cents. * @example 200 */ taxes_amount_cents: number; /** * @description The total amount in cents, tax included. * @example 123 */ total_amount_cents: number; /** @description Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage. */ charges_usage: components["schemas"]["CustomerChargeUsageObject"][]; }; CustomerUsage: { customer_usage: components["schemas"]["CustomerUsageObject"]; }; /** @description Array of filter object, representing multiple dimensions for a charge item. */ CustomerProjectedChargeFiltersUsageObject: { /** * @description The number of units consumed for a specific charge filter related to a charge item. * @example 0.9 */ units: string; /** * @description The projected number of units that can be consumed for a specific charge filter related to a charge item. * @example 1.8 */ projected_units: string; /** * @description The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item. * @example 1000 */ amount_cents: number; /** * @description The projected amount in cents, tax excluded, that can be consumed for a specific charge filter related to a charge item. * @example 2000 */ projected_amount_cents: number; /** * @description The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts. * @example 10 */ events_count: number; /** * @description Specifies the name that will be displayed on an invoice. * @example AWS eu-east-1 */ invoice_display_name?: string; pricing_unit_details?: components["schemas"]["UsagePricingUnitDetailsObject"]; /** * @description List of filter values applied to the usage. * @example { * "region": [ * "us-east-1" * ] * } */ values: { [key: string]: string[]; }; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; projected_presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; }[]; /** @description Array of aggregated fees, grouped by the event properties defined in a `standard` charge model. */ CustomerProjectedChargeGroupedUsageObject: { /** * @description The amount in cents, tax excluded, consumed for a specific group related to a charge item. * @example 1000 */ amount_cents: number; /** * @description The projected amount in cents, tax excluded, that can be consumed for a specific group related to a charge item. * @example 2000 */ projected_amount_cents: number; /** * @description The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts. * @example 10 */ events_count: number; /** * @description The number of units consumed for a specific group related to a charge item. * @example 0.9 */ units: string; /** * @description The projected number of units that can be consumed for a specific group related to a charge item. * @example 1.8 */ projected_units: string; pricing_unit_details?: components["schemas"]["UsagePricingUnitDetailsObject"]; /** @description Key value list of event properties aggregated by the charge model */ grouped_by: { [key: string]: string; }; filters: components["schemas"]["CustomerProjectedChargeFiltersUsageObject"]; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; projected_presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; }[]; CustomerProjectedChargeUsageObject: { /** * @description The number of units consumed by the customer for a specific charge item. * @example 1.0 */ units: string; /** * @description The projected number of units that can be consumed by the customer for a specific charge item. * @example 2.0 */ projected_units: string; /** * @description The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts. * @example 10 */ events_count: number; /** * @description The amount in cents, tax excluded, consumed by the customer for a specific charge item. * @example 123 */ amount_cents: number; /** * @description The projected amount in cents, tax excluded, that can be consumed by the customer for a specific charge item. * @example 256 */ projected_amount_cents: number; /** * @description The currency of a usage item consumed by the customer. * @example EUR */ amount_currency: components["schemas"]["Currency"]; pricing_unit_details?: components["schemas"]["UsagePricingUnitDetailsObject"]; /** @description Object listing all the properties for a specific charge item. */ charge: { /** * Format: uuid * @description Unique identifier assigned to the charge within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the charge's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The pricing model applied to this charge. Possible values are standard, `graduated`, `percentage`, `package` or `volume`. * @example graduated * @enum {string} */ charge_model: "standard" | "graduated" | "package" | "percentage" | "volume"; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string; }; /** @description The related feature object. */ feature: { /** * Format: uuid * @description Unique identifier assigned to the feature within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the feature's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The name of the feature used for this charge. * @example Storage */ name: string; /** * @description The code of the feature used for this charge. * @example storage */ code: string; /** * @description The aggregation type of the feature used for this charge. Possible values are `count_agg`, `sum_agg`, `max_agg` or `unique_count_agg`. * @example sum_agg * @enum {string} */ aggregation_type: "count_agg" | "sum_agg" | "max_agg" | "unique_count_agg" | "weighted_sum_agg" | "latest_agg"; }; filters?: components["schemas"]["CustomerProjectedChargeFiltersUsageObject"]; grouped_usage: components["schemas"]["CustomerProjectedChargeGroupedUsageObject"]; presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; projected_presentation_breakdowns?: components["schemas"]["PresentationBreakdownsObject"]; }; CustomerProjectedUsageObject: { /** * Format: date-time * @description The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC). * @example 2022-07-01T00:00:00Z */ from_datetime: string; /** * Format: date-time * @description The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC). * @example 2022-07-31T23:59:59Z */ to_datetime: string; /** * Format: date * @description The date of creation of the invoice. * @example 2022-08-01 */ issuing_date: string; /** * Format: uuid * @description A unique identifier associated with the invoice related to this particular usage record. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id?: string | null; /** * @description The currency of the customer's current usage. * @example EUR */ currency?: components["schemas"]["Currency"]; /** * @description The amount in cents, tax excluded. * @example 123 */ amount_cents: number; /** * @description The projected amount in cents, tax excluded. * @example 256 */ projected_amount_cents: number; /** * @description The tax amount in cents. * @example 200 */ taxes_amount_cents: number; /** * @description The total amount in cents, tax included. * @example 123 */ total_amount_cents: number; /** @description Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage. */ charges_usage: components["schemas"]["CustomerProjectedChargeUsageObject"][]; }; CustomerProjectedUsage: { customer_projected_usage: components["schemas"]["CustomerProjectedUsageObject"]; }; CustomerPastUsage: { usage_periods: components["schemas"]["CustomerUsageObject"][]; meta: components["schemas"]["PaginationMeta"]; }; CustomerCheckoutUrl: { /** * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The Payment Provider name linked to the Customer. * @example stripe */ payment_provider: string; /** * @description Code of the payment provider * @example Stripe Prod */ payment_provider_code?: string; /** * @description The new generated Payment Provider Checkout URL for the Customer. * @example https://foo.bar */ checkout_url?: string; }; PaymentMethodObject: { /** * Format: uuid * @description The unique identifier of the payment method, created by Nozle. * @example 4cf085a7-c196-4f07-a543-97c50ec6e8b2 */ nozle_id: string; /** * @description Indicates whether this payment method is the default one for the customer. * @example true */ is_default: boolean; /** * @description Code of the payment provider associated with this payment method. * @example stripe_prod */ payment_provider_code?: string | null; /** * @description Human-readable name of the payment provider. * @example Stripe */ payment_provider_name?: string | null; /** * @description The type of the payment provider. * @example stripe * @enum {string} */ payment_provider_type: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash"; /** * @description Unique identifier of the payment method within the payment provider. * @example pm_1N8ZQX2eZvKYlo2CkL9Y8XYZ */ provider_method_id: string; /** * Format: date-time * @description Timestamp when the payment method was created in Nozle's database. * @example 2025-01-21T00:10:29Z */ created_at: string; }; PaymentMethodsPaginated: { payment_methods: components["schemas"]["PaymentMethodObject"][]; meta: components["schemas"]["PaginationMeta"]; }; PaymentMethod: { payment_method: components["schemas"]["PaymentMethodObject"]; }; EventObject: { /** * Format: uuid * @description Unique identifier assigned to the event within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the event's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id?: string | null; /** * @description This field represents a unique identifier for the event. It is crucial for ensuring idempotency, meaning that each event can be uniquely identified and processed without causing any unintended side effects. * @example transaction_1234567890 */ transaction_id: string; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string | null; /** * @description The code that identifies a targeted feature. It is essential that this code matches the `code` property of one of your active features. If the provided code does not correspond to any active feature, it will be ignored during the process. * @example storage */ code: string; /** * Format: date-time * @description This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception. * @example 2022-04-29T08:59:51.123Z */ timestamp: string; /** * @description The precise total amount that was sent in the event payload. This filed is used by the `dynamic` pricing model. * @example 1234.56 */ precise_total_amount_cents?: string | null; /** * @description This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted feature employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. * @example { * "gb": 10 * } */ properties?: { /** * @description The `operation_type` field is only necessary when adding or removing a specific unit when the targeted feature adopts a `unique_count_agg` aggregation method. In other cases, the `operation_type` field is not required. The valid values for the `operation_type` field are `add` or `remove`, which indicate whether the unit is being added or removed from the unique count aggregation, respectively. * @enum {string|null} */ operation_type?: "add" | "remove" | null; } & { [key: string]: string | number; }; /** * Format: uuid * @description Unique identifier assigned to the subscription within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the subscription's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id: string | null; /** * @description The unique identifier of the subscription within your application. It is a mandatory field when the customer possesses multiple subscriptions or when the `external_customer_id` is not provided. * @example sub_1234567890 */ external_subscription_id: string | null; /** * Format: date-time * @description The creation date of the event's record in the Nozle application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Nozle application * @example 2022-04-29T08:59:51Z */ created_at?: string | null; }; EventsPaginated: { events: components["schemas"]["EventObject"][]; meta: components["schemas"]["PaginationMeta"]; }; EventInputObject: { /** * @description Organization-wide identifier for one logical Feature Event and all of its retries. * If omitted, Nozle generates a version 7 universally unique identifier and returns it in the response. * Reusing an identifier with a different subscription, timestamp, code, or properties is a conflict rather than a new event. * @example transaction_1234567890 */ transaction_id?: string; /** * @description External ID of the subscription the event is billed to. Send it or `external_customer_id`; with neither the response is `422 validation_errors` with `external_subscription_id: [value_is_mandatory]`. When it is given, `external_customer_id` is ignored. * @example sub_1234567890 */ external_subscription_id?: string; /** * @description The code that identifies a targeted feature. It is essential that this code matches the `code` property of one of your active features. If the provided code does not correspond to any active feature, it will be ignored during the process. * @example storage */ code: string; /** * @description This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). * If this timestamp is not provided, the API will automatically set it to the time of event reception. * You can also provide miliseconds precision by appending decimals to the timestamp. * @example 1651240791.123 */ timestamp?: number | string; /** * @description The precise total amount in cents with precision used by the `dynamic` pricing model to compute the usage amount. * @example 1234.56 */ precise_total_amount_cents?: string | null; /** * @description This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted feature employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. * @example { * "gb": 10 * } */ properties?: { [key: string]: string | number; } | null; /** * @description Used only when `external_subscription_id` is blank. The event is billed to this customer's single active subscription and stored with its `external_subscription_id`. An unknown customer or one with no active subscription returns `422 active_subscription_not_found`, and several active subscriptions return `422 active_subscription_ambiguous`, with `error_details` `{"external_customer_id": [code]}`. * @example cust_123 */ external_customer_id?: string; }; CostEventInput: { /** * @description Organization-scoped retry identifier. Nozle generates a version 7 universally unique identifier when omitted. * @example cost_01994d7e */ cost_event_id?: string; /** * @description Code of the Cost Event Meter used to interpret quantity and dimensions. * @example ai_tokens */ cost_meter_code: string; /** * @description Organization-scoped transaction identifier of the parent Feature Event. The Cost Event may arrive before its parent. * @example feature_01994d7e */ parent_transaction_id?: string; /** * @description Customer receiving the cost. Required when no parent Feature Event is supplied. * @example customer_123 */ external_customer_id?: string; /** * @description Optional upstream provider request identifier for investigation and reconciliation. * @example provider_request_987 */ request_id?: string; /** * @description Optional logical operation within the parent Feature Event. * @example planning */ operation_key?: string; /** * @description Quantity and dimensions consumed by the Cost Event Meter. * @example { * "tokens": 900, * "model": "configured-model-a", * "type": "input" * } */ properties?: { [key: string]: unknown; }; /** * @description Event time. A number of Unix seconds (fractions allowed), a numeric string, or an RFC 3339 string with a time zone offset or `Z`. Nozle uses the reception time when omitted. A date without a time, a time without an offset, and zero or negative seconds are rejected. Strings are accepted from the Engine release that includes this change; before it, only a number is accepted. * @example 1788345001 */ timestamp?: number | string; } | unknown | unknown; CostEventAccepted: { /** @enum {string} */ status: "accepted"; /** @example cost_01994d7e */ cost_event_id: string; }; SharedCostAllocationInput: { /** * Format: date-time * @description Any timestamp within the allocation period to preview or finalize. * @example 2026-08-01T00:00:00Z */ allocation_period_start: string; }; SharedCostCustomerAllocation: { /** @example customer_123 */ external_customer_id: string; /** * @description Exact decimal allocation in the organization's reporting currency. * @example 10.000000000000 */ amount: string; }; SharedCostAllocationPreview: { /** Format: date-time */ allocation_period_start: string; /** Format: date-time */ allocation_period_end: string; /** Format: date-time */ eligibility_period_start: string; /** Format: date-time */ eligibility_period_end: string; /** @example 1000.000000000000 */ recognized_amount: string; /** @example USD */ currency: string; /** @example 100 */ consumer_count: number; allocations: components["schemas"]["SharedCostCustomerAllocation"][]; }; SharedCostAllocationRun: { /** Format: uuid */ id: string; /** @enum {string} */ status: "completed" | "unallocated"; /** Format: date-time */ allocation_period_start: string; /** Format: date-time */ allocation_period_end: string; /** @example 1000.000000000000 */ recognized_amount: string; /** @example USD */ currency: string; /** @example 100 */ consumer_count: number; }; CostIntelligenceSummary: { /** @example 1234.567890000000 */ total_cost: string; /** @example 1034.567890000000 */ direct_cost: string; /** @example 200.000000000000 */ shared_cost: string; /** * Format: int64 * @example 1842 */ ledger_entry_count: number; /** @example USD */ currency: string; }; CostIntelligenceBreakdown: { /** @example copilot_action */ key: string; /** @example 42.125000000000 */ cost: string; /** * Format: int64 * @example 17 */ customer_count: number; /** * Format: int64 * @example 830 */ entry_count: number; /** @example USD */ currency: string; }; CostIntelligenceLedgerEntry: { /** Format: uuid */ ledger_entry_id: string; /** @example cost_01994d7e */ source_external_id: string; /** @example feature_01994d7e */ parent_transaction_id?: string; /** @example customer_123 */ external_customer_id?: string; /** @example copilot_action */ feature_code?: string; /** @example direct_cost */ entry_kind: string; /** @example rated */ status: string; /** @example 900 */ quantity: string; /** @example 0.002250000000 */ amount: string; /** @example USD */ currency: string; /** * @description Canonical serialized dimensions used to select the Cost Rule. * @example {"model":"configured-model-a","type":"input"} */ filter_values: string; /** Format: date-time */ occurred_at: string; }; CostIntelligenceUncostedSource: { /** @enum {string} */ source_type: "feature_event" | "cost_event"; source_external_id: string; feature_code?: string; external_customer_id?: string; /** @enum {string} */ status: "uncosted" | "pending_parent" | "excluded_from_margin"; failure_code?: string; failure_message?: string; /** Format: date-time */ occurred_at: string; }; CostIntelligenceProcessingConflict: { /** @enum {string} */ source_type: "feature_event" | "cost_event"; source_external_id: string; accepted_payload_hash: string; conflicting_payload_hash: string; source_topic: string; source_partition: number; /** Format: int64 */ source_offset: number; /** Format: date-time */ detected_at: string; }; CostIntelligenceReport: { /** Format: date-time */ from: string; /** Format: date-time */ to: string; summary: components["schemas"]["CostIntelligenceSummary"]; features: components["schemas"]["CostIntelligenceBreakdown"][]; customers: components["schemas"]["CostIntelligenceBreakdown"][]; cost_events: components["schemas"]["CostIntelligenceLedgerEntry"][]; shared_costs: components["schemas"]["CostIntelligenceLedgerEntry"][]; uncosted: components["schemas"]["CostIntelligenceUncostedSource"][]; conflicts: components["schemas"]["CostIntelligenceProcessingConflict"][]; }; EventInput: { event: components["schemas"]["EventInputObject"]; }; EventCreated: { event: components["schemas"]["EventObject"] & { /** * @description The value will always be null in this response as the event processing is done asynchronously * @example null */ customer_id?: null; }; }; EventBatchInput: { events: components["schemas"]["EventInputObject"][]; }; EventsCreated: { events: (components["schemas"]["EventObject"] & { /** * @description The value will always be null in this response as the event processing is done asynchronously * @example null */ customer_id?: null; })[]; /** * @description Engine 2.22.0, `POST /events/batch` only. Present when events were refused because their customer is blocked by its [dunning policy](/guides/billing/dunning): keyed by the position of each refused event in the request. The other events were stored. * @example { * "2": { * "external_customer_id": [ * "customer_payment_overdue" * ] * } * } */ error_details?: { [key: string]: { [key: string]: string[]; }; }; }; EventEstimateFeesInput: { event: { /** * @description The code that identifies a targeted feature. It is essential that this code matches the `code` property of one of your active features. If the provided code does not correspond to any active feature, it will be ignored during the process. * @example storage */ code: string; /** * @description The unique identifier of the subscription within your application. * @example sub_1234567890 */ external_subscription_id: string; /** @description This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted feature employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. */ properties?: Record; }; }; Fees: { fees: components["schemas"]["FeeObject"][]; }; EventEstimateInstantFeesInput: { event: { /** * @description The code that identifies a targeted feature. It is essential that this code matches the `code` property of one of your active features. If the provided code does not correspond to any active feature, it will be ignored during the process. * @example storage */ code: string; /** * @description The unique identifier of the subscription within your application. * @example sub_1234567890 */ external_subscription_id: string; /** @description This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted feature employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. */ properties?: Record; /** * @description This field represents a unique identifier for the event. * @example transaction_1234567890 */ transaction_id?: string | null; }; }; FeeEstimateObject: { nozle_id?: null; /** * Format: uuid * @description Unique identifier assigned to the charge that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ charge_id?: string; /** * Format: uuid * @description Unique identifier assigned to the charge filter that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ charge_filter_id?: string | null; invoice_id?: null; true_up_fee_id?: null; true_up_parent_fee_id?: null; /** * Format: uuid * @description Unique identifier assigned to the subscription, created by Nozle. This field is specifically displayed when the fee type is charge or subscription. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id?: string; /** * Format: uuid * @description Unique identifier assigned to the customer, created by Nozle. This field is specifically displayed when the fee type is charge or subscription. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id?: string; /** * @description Unique identifier assigned to the customer in your application. This field is specifically displayed when the fee type is charge or subscription. * @example external_id */ external_customer_id?: string; /** * @description Unique identifier assigned to the subscription in your application. This field is specifically displayed when the fee type is charge or subscription. * @example external_id */ external_subscription_id?: string; /** * @description The cost of this specific fee, excluding any applicable taxes. * @example 100 */ amount_cents: number; /** * @description The cost of this specific fee, excluding any applicable taxes, with precision. * @example 1.0001 */ precise_amount?: number; /** * @description The cost of this specific fee, including any applicable taxes, with precision. * @example 1.0212 */ precise_total_amount?: number; /** * @description The currency of this specific fee. It indicates the monetary unit in which the fee's cost is expressed. * @example EUR */ amount_currency: components["schemas"]["Currency"]; /** * @description The cost of the tax associated with this specific fee. * @example 0 */ taxes_amount_cents: number; /** * @description The cost of the tax associated with this specific fee, with precision. * @example 0 */ taxes_precise_amount?: number; /** * @description The tax rate associated with this specific fee. * @example 20 */ taxes_rate: number; /** * @description The number of units used to charge the customer. This field indicates the quantity or count of units consumed or utilized in the context of the charge. It helps in determining the basis for calculating the fee or cost associated with the usage of the service or product provided to the customer. * @example 0.32 */ units: string; description?: null; /** * @description The unit amount of the fee per unit, with precision. * @example 312.5 */ precise_unit_amount: number; /** * @description The coupon amount applied to the estimated instant fee. It will always returns 0 * @example 0.0 */ precise_coupons_amount_cents?: string; /** * @description The cost of this specific fee, including any applicable taxes. * @example 120 */ total_amount_cents: number; /** * @description The currency of this specific fee, including any applicable taxes. * @example EUR */ total_amount_currency: components["schemas"]["Currency"]; /** * @description The number of events that have been sent and used to charge the customer. This field indicates the count or quantity of events that have been processed and considered in the charging process. * @example 1 */ events_count?: number; /** * @description Flag that indicates whether the fee was paid in advance. It serves as a boolean value, where `true` represents that the fee was paid in advance (straightaway), and `false` indicates that the fee was not paid in arrears (at the end of the period). * @example true */ pay_in_advance: boolean; /** * @description Flag that indicates whether the fee was included on the invoice. It serves as a boolean value, where `true` represents that the fee was included on the invoice, and `false` indicates that the fee was not included on the invoice. * @example true */ invoiceable: boolean; /** * @description Indicates the payment status of the fee. It represents the current status of the payment associated with the fee. The value will always `pending`. * @example pending * @enum {string} */ payment_status: "pending"; created_at?: null; succeeded_at?: null; failed_at?: null; refunded_at?: null; /** * @description Unique identifier assigned to the transaction. This field is specifically displayed when the fee type is `charge` and the payment for the fee is made in advance (`pay_in_advance` is set to `true`). * @example transaction_1234567890 */ event_transaction_id?: string; amount_details?: null; /** @description Item attached to the fee */ item: { /** * @description The fee type. The value will be `charge`. * @example charge * @enum {string} */ type: "charge"; /** * @description The code of the fee item. It will be the code of the `feature`. * @example startup */ code: string; /** * @description The name of the fee item. It will be the name of the `feature`. * @example Startup */ name: string; /** * @description The description of the fee item. It will be the name of the `feature`. * @example Startup description */ description?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup Fee (SF1) */ invoice_display_name?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the actual charge filter values will be used as the default display name. * @example AWS eu-east-1 */ filter_invoice_display_name?: string | null; /** @description Key value list of event properties */ filters?: { [key: string]: string[]; } | null; /** * Format: uuid * @description Unique identifier of the fee item, created by Nozle. It will be the identifier of the `feature`. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ item_id: string; /** * @description The type of the fee item. Values is `Feature`. * @example Feature * @enum {string} */ item_type: "Feature"; /** @description Key value list of event properties aggregated by the charge model */ grouped_by?: { [key: string]: string; }; }; }; FeesEstimate: { fees: components["schemas"]["FeeEstimateObject"][]; }; EventBatchEstimateInstantFeesInput: { events: components["schemas"]["EventEstimateInstantFeesInput"][]; }; Event: { event: components["schemas"]["EventObject"]; }; FeesPaginated: { fees: components["schemas"]["FeeObject"][]; meta: components["schemas"]["PaginationMeta"]; }; Fee: { fee: components["schemas"]["FeeObject"]; }; FeeUpdateInput: { fee: { /** * @description The payment status of the fee. Possible values are `pending`, `succeeded`, `failed` or `refunded`. * @example succeeded * @enum {string} */ payment_status: "pending" | "succeeded" | "failed" | "refunded"; }; }; InvoiceOneOffCreateInput: { invoice: { /** * @description Unique identifier assigned to the customer in your application. * @example hooli_1234 */ external_customer_id: string; /** * @description The code of the billing entity to issue the invoice from. If not provided, the customer's billing entity is used. * @example default */ billing_entity_code?: string; /** * @description The currency of the invoice. * @example EUR */ currency?: components["schemas"]["Currency"]; fees: { /** * @description The code of the add-on used as invoice item. * @example setup_fee */ add_on_code: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup Fee (SF1) */ invoice_display_name?: string; /** * @description The amount of the fee per unit, expressed in cents. By default, the amount of the add-on is used. * @example 12000 */ unit_amount_cents?: number | null; /** * @description The quantity of units associated with the fee. By default, only 1 unit is added to the invoice. * @example 2.5 */ units?: string | null; /** * @description This is a description * @example The description of the fee line item in the invoice. By default, the description of the add-on is used. */ description?: string | null; /** * Format: date-time * @description The lower boundary of the invoice billing interval. The `from_datetime` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ from_datetime?: string; /** * Format: date-time * @description The upper boundary of the invoice billing interval. The `to_datetime` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ to_datetime?: string; tax_codes?: components["schemas"]["TaxCodes"]; /** * @description If true, the invoice will be created but not sent to the payment provider. * @default false * @example true */ skip_psp: boolean | null; }[]; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description Optional payment method to use for processing the invoice payment. */ payment_method?: components["schemas"]["PaymentMethodReference"]; }; }; BillingPeriodObject: { /** * Format: uuid * @description Unique identifier assigned to the subscription, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id: string; /** * @description Unique identifier assigned to the subscription in your application. * @example external_id */ external_subscription_id: string; /** * Format: uuid * @description Unique identifier assigned to the plan, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ plan_id: string; /** * Format: date-time * @description The beginning date of the subscription billing period. This field indicates the start date of the billing period associated with the subscription fee. * @example 2022-04-29T08:59:51Z */ subscription_from_datetime: string; /** * Format: date-time * @description The ending date of the subscription billing period. This field indicates the end date of the billing period associated with the subscription fee. * @example 2022-05-29T08:59:51Z */ subscription_to_datetime: string; /** * Format: date-time * @description The beginning date of the period that covers the charge fees. It is applicable only to the `charge` fees attached to the subscription. This field indicates the start date of the billing period or subscription period associated with the fees. * @example 2022-04-29T08:59:51Z */ charges_from_datetime: string; /** * Format: date-time * @description The ending date of the period that covers the charge fees. It is applicable only to the `charge` fees attached to the subscription. This field indicates the end date of the billing period or subscription period associated with the fees. * @example 2022-05-29T08:59:51Z */ charges_to_datetime: string; /** * @description The reason explaining why this subscription appears on the invoice. * @example subscription_starting * @enum {string} */ invoicing_reason: "subscription_starting" | "subscription_periodic" | "subscription_terminating" | "in_advance_charge" | "in_advance_charge_periodic" | "progressive_billing"; fixed_charges_from_datetime?: string; fixed_charges_to_datetime?: string; }; InvoiceObjectExtended: components["schemas"]["InvoiceObject"] & { billing_periods?: components["schemas"]["BillingPeriodObject"][]; credits?: components["schemas"]["CreditObject"][]; fees?: components["schemas"]["FeeObject"][]; subscriptions?: components["schemas"]["SubscriptionObject"][]; error_details?: components["schemas"]["ErrorDetailObject"][]; total_due_amount_cents?: number; total_paid_amount_cents?: number; total_offsetted_credit_note_amount_cents?: number; xml_url?: string | null; voided_at?: string | null; }; Invoice: { invoice: components["schemas"]["InvoiceObjectExtended"]; }; InvoiceUpdateInput: { invoice: { /** * @description The payment status of the invoice. Possible values are `pending`, `failed` or `succeeded`. * @example succeeded * @enum {string} */ payment_status?: "pending" | "succeeded" | "failed"; metadata?: { /** * Format: uuid * @description The metadata object identifier. Only required when updating existing metadata. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id?: string; /** * @description The key in the key-value pair of the metadata. * @example digital_ref_id */ key?: string; /** * @description The value in the key-value pair of the metadata. * @example INV-0123456-98765 */ value?: string; }[]; }; }; /** @description . */ InvoicePaymentUrl: { invoice_payment_details?: { /** * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id?: string; /** * @description Unique identifier assigned to the invoice within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the invoice's record within the Nozle system * @example 1e501a90-1a90-1a90-1a90-1a901a901a80 */ invoice_id?: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id?: string; /** * @description The Payment Provider name linked to the Customer. * @example stripe */ payment_provider?: string; /** * @description The generated Payment URL for the Invoice. * @example https://foo.bar */ payment_url?: string; }; }; InvoicePreviewInput: { customer: { /** * @description The first line of the billing address * @example 5230 Penfield Ave */ address_line1?: string; /** * @description The second line of the billing address * @example null */ address_line2?: string | null; /** * @description The city of the customer's billing address * @example Woodland Hills */ city?: string; /** * @description Country code of the customer's billing address. Format must be ISO 3166 (alpha-2) * @example US */ country?: components["schemas"]["Country"]; /** * @description Unique identifier assigned to the customer in your application. * @example hooli_1234 */ external_id?: string; integration_customers?: { /** * @description The integration type used for accounting and tax syncs. * Accepted values: `anrok`. * @example anrok * @enum {string} */ integration_type: "anrok"; /** * @description Unique code used to identify an integration connection. * @example anrok1 */ integration_code: string; }[]; /** * @description The full name of the customer * @example Gavin Belson */ name?: string; /** * @description The currency of the invoice. * @example EUR */ currency?: components["schemas"]["Currency"]; shipping_address?: components["schemas"]["Address"]; /** * @description The state of the customer's billing address * @example CA */ state?: string; /** * @description The tax identification number of the customer * @example EU123456789 */ tax_identification_number?: string; /** @description The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone */ timezone?: components["schemas"]["Timezone"]; }; /** * @description The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance. * @example startup */ plan_code?: string; /** * Format: date-time * @description The anniversary date and time of the initial subscription. This date serves as the basis for billing subscriptions with `anniversary` billing time. The `anniversary_date` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ subscription_at?: string; /** * @description The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration). * @example anniversary * @enum {string} */ billing_time?: "calendar" | "anniversary"; coupons?: { /** * @description The name of the coupon. * @example Startup Deal */ name?: string; /** * @description Unique code used to identify the coupon. * @example startup_deal */ code: string; /** * @description The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`. * * - If set to `fixed_amount`, the coupon represents a fixed amount discount. * - If set to `percentage`, the coupon represents a percentage-based discount. * @example fixed_amount * @enum {string} */ coupon_type?: "fixed_amount" | "percentage"; /** * @description The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. * @example 5000 */ amount_cents?: number | null; /** * @description The currency of the coupon. This field is required only for coupon with `fixed_amount` type. * @example USD */ amount_currency?: components["schemas"]["CurrencyOrNull"]; /** @description The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. */ percentage_rate?: string | null; /** * @description Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type * @example 6 */ frequency_duration?: number | null; }[]; /** * @description The code of the billing entity to which will be associated a customer if the external_id is not provided. If billing_entity_code is not provided, default billing_entity of organization will be used. * @example acme_corp */ billing_entity_code?: string; }; /** @description Parameters available when voiding an invoice that optionally generate credit notes. */ InvoiceVoidInput: { /** * @description Set to `true` to force voiding the invoice and generate a credit note. * @example true */ generate_credit_note?: boolean; /** * @description Portion of the invoice amount (in cents) to be refunded to the customer in the generated credit note. * @example 2000 */ refund_amount?: number; /** * @description Portion of the invoice amount (in cents) to be credited to the customer's balance in the generated credit note. * @example 1150 */ credit_amount?: number; }; /** @description The custom billing settings for your organization. */ OrganizationBillingConfiguration: { /** * @description When the billing periods of new subscriptions start: `calendar` (the first of the month) or `anniversary` (the day the subscription starts). A subscription, checkout or Entity checkout can set its own `billing_time`; without one it follows this setting. Changing it does not move existing subscriptions. * @example calendar * @enum {string} */ billing_alignment?: "calendar" | "anniversary"; /** * @description The customer invoice message that appears at the bottom of each billing documents. * @example This is my customer footer */ invoice_footer?: string | null; /** * @description The grace period, expressed in days, for finalizing the invoice. This period refers to the additional time granted to your customers beyond the invoice due date to adjust usage and line items. Can be overwritten by the customer's grace period. * @example 3 */ invoice_grace_period?: number; /** * @description The locale of the billing documents, expressed in the ISO 639-1 format. This field indicates the language or regional variant used for the documents content issued or the embeddable customer portal. * @example en */ document_locale?: string; }; OrganizationUpdateInput: { organization: { /** * @description The URL of your newest updated webhook endpoint. This URL allows your organization to receive important messages, notifications, or data from the Nozle system. By configuring your webhook endpoint to this URL, you can ensure that your organization stays informed and receives relevant information in a timely manner. * @example https://webhook.brex.com */ webhook_url?: string | null; /** * @description The country of your organization. * @example US */ country?: components["schemas"]["CountryOrNull"]; /** * @description The default currency of an organization. * @example USD */ default_currency?: components["schemas"]["Currency"]; /** * @description The first line of your organization's billing address. * @example 100 Brex Street */ address_line1?: string | null; /** * @description The second line of your organization's billing address. * @example null */ address_line2?: string | null; /** * @description The state of your organization's billing address. * @example NYC */ state?: string | null; /** * @description The zipcode of your organization's billing address. * @example 10000 */ zipcode?: string | null; /** * Format: email * @description The email address of your organization used to bill your customers. * @example brex@brex.com */ email?: string | null; /** * @description The city of your organization's billing address. * @example New York */ city?: string | null; /** * @description The legal name of your organization. * @example null */ legal_name?: string | null; /** * @description The legal number of your organization. * @example null */ legal_number?: string | null; /** * @description This parameter configures the method of incrementing invoice numbers for your customers. * * - `per_customer`: Invoice numbers are incremented individually for each customer. This means every customer will have their own unique sequence of invoice numbers, separate from other customers. It ensures that each customer's invoice numbers follow a distinct and isolated numbering pattern. * - `per_organization`: Invoice number incrementation is made across your entire organization. Rather than individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers. Invoices are incremented per month (dynamic value used is YYYYMM), and invoice numbers are reset at the end of each month. * * The default value for `document_numbering` is set to `per_customer`, meaning that, unless changed, invoice numbers will increment uniquely for each customer. * @example per_customer * @enum {string} */ document_numbering?: "per_customer" | "per_organization"; /** * @description Sets the prefix for invoices and credit notes. Default is the first three letters of your organization name plus the last four digits of your organization ID. Customizable within 1-10 characters, and automatically capitalized by Nozle. * @example ORG-1234 */ document_number_prefix?: string; /** * @description The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized. * @example 30 */ net_payment_term?: number; /** * @description The tax identification number of your organization. * @example US123456789 */ tax_identification_number?: string | null; /** * @description Your organization's timezone, used for billing purposes in your own local time. Can be overwritten by the customer's timezone. * @example America/New_York */ timezone?: components["schemas"]["Timezone"]; /** * @description Represents the email settings of the organization. It allows you to define which documents are sent by email. The field value determines the types of documents that trigger email notifications. Possible values for are `invoice.finalized` and `credit_note.created`. By configuring this field, you can specify whether invoices, credit notes, or both should be sent to recipients via email. * @example [ * "invoice.finalized", * "credit_note.created" * ] */ email_settings?: ("invoice.finalized" | "credit_note.created")[]; billing_configuration?: components["schemas"]["OrganizationBillingConfiguration"]; /** * @description Determines whether invoices with a zero total amount should be finalized. If set to true, zero amount invoices will be finalized. If set to false, zero amount invoices will not be finalized. * @example false */ finalize_zero_amount_invoice?: boolean; /** * @description HTTPS origins your checkout `return_url` and `success_url` may point to, in addition to Nozle's own apps. Up to 20; each is a scheme and host only (no path, query or user info) and is stored lowercase without a trailing slash. An invalid origin answers `422` with `value_is_invalid` in `checkout_return_origins`. Another organization's origin is never accepted for your checkouts. Requires the `developers:manage` permission. * @example [ * "https://app.acme.com" * ] */ checkout_return_origins?: string[]; /** * @description HTTPS URL on one of the allowed origins where the customer returns when a checkout gives no `return_url`. When it is `null`, the customer returns to the first of `checkout_return_origins`, else to the payment provider's success URL. A URL off the allowed origins answers `422` with `invalid_or_untrusted` in `checkout_default_return_url`. * @example https://app.acme.com/billing/done */ checkout_default_return_url?: string | null; }; }; OrganizationObject: { /** * Format: uuid * @description Unique identifier assigned to the organization within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the organization's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The name of your organization. * @example Name1 */ name: string; /** * Format: date-time * @description The date of creation of your organization, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-05-02T13:04:09Z */ created_at: string | null; /** * @description The URL of your newest updated webhook endpoint. This URL allows your organization to receive important messages, notifications, or data from the Nozle system. By configuring your webhook endpoint to this URL, you can ensure that your organization stays informed and receives relevant information in a timely manner. * @example https://webhook.brex.com */ webhook_url?: string | null; /** * @description The array containing your webhooks URLs. * @example [ * "https://webhook.brex.com", * "https://webhook2.brex.com" * ] */ webhook_urls?: string[] | null; /** * @description The country of your organization. * @example US */ country?: components["schemas"]["CountryOrNull"]; /** * @description The default currency of an organization. * @example USD */ default_currency?: components["schemas"]["Currency"]; /** * @description The first line of your organization's billing address. * @example 100 Brex Street */ address_line1?: string | null; /** * @description The second line of your organization's billing address. * @example null */ address_line2?: string | null; /** * @description The state of your organization's billing address. * @example NYC */ state?: string | null; /** * @description The zipcode of your organization's billing address. * @example 10000 */ zipcode?: string | null; /** * Format: email * @description The email address of your organization used to bill your customers. * @example brex@brex.com */ email?: string | null; /** * @description The city of your organization's billing address. * @example New York */ city?: string | null; /** * @description The legal name of your organization. * @example null */ legal_name?: string | null; /** * @description The legal number of your organization. * @example null */ legal_number?: string | null; /** * @description This parameter configures the method of incrementing invoice numbers for your customers. * * - `per_customer`: Invoice numbers are incremented individually for each customer. This means every customer will have their own unique sequence of invoice numbers, separate from other customers. It ensures that each customer's invoice numbers follow a distinct and isolated numbering pattern. * - `per_organization`: Invoice number incrementation is made across your entire organization. Rather than individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers. Invoices are incremented per month (dynamic value used is YYYYMM), and invoice numbers are reset at the end of each month. * * The default value for `document_numbering` is set to `per_customer`, meaning that, unless changed, invoice numbers will increment uniquely for each customer. * @example per_customer * @enum {string} */ document_numbering: "per_customer" | "per_organization"; /** * @description Sets the prefix for invoices and credit notes. Default is the first three letters of your organization name plus the last four digits of your organization ID. Customizable within 1-10 characters, and automatically capitalized by Nozle. * @example ORG-1234 */ document_number_prefix: string; /** * @description The documents Nozle sends by email for your organization. * @example [ * "invoice.finalized", * "credit_note.created" * ] */ email_settings: ("invoice.finalized" | "credit_note.created" | "payment_receipt.created")[]; /** * @description The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized. * @example 30 */ net_payment_term?: number; /** * @description The tax identification number of your organization. * @example US123456789 */ tax_identification_number?: string | null; /** * @description Your organization's timezone, used for billing purposes in your own local time. Can be overwritten by the customer's timezone. * @example America/New_York */ timezone?: components["schemas"]["Timezone"]; billing_configuration: components["schemas"]["OrganizationBillingConfiguration"]; /** @description List of default organization taxes */ taxes?: components["schemas"]["TaxObject"][]; /** * @description HTTPS origins your checkout return URLs may point to, in addition to Nozle's own apps. Set with `PUT /organizations`. * @example [ * "https://app.acme.com" * ] */ checkout_return_origins?: string[]; /** * @description Where the customer returns when a checkout gives no `return_url`. When it is `null`, the first of `checkout_return_origins`, else the payment provider's success URL. * @example https://app.acme.com/billing/done */ checkout_default_return_url?: string | null; /** * @description Indicates whether invoices with a zero total amount should be finalized. If set to true, zero amount invoices will be finalized. If set to false, zero amount invoices will not be finalized. * @example false */ finalize_zero_amount_invoice?: boolean; /** * @example clickhouse * @enum {string} */ events_store?: "clickhouse" | "postgres"; }; Organization: { organization: components["schemas"]["OrganizationObject"]; }; PaymentReceiptObject: { /** * Format: uuid * @description Unique identifier of the payment receipt, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: date-time * @description The date and time when the payment receipt was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the payment receipt was initially created. * @example 2022-04-29T08:59:51Z */ created_at: string; /** * @description The unique number assigned to the payment receipt. * @example LAG-1234-001-002 */ number: string; payment: components["schemas"]["PaymentObject"]; }; PaymentReceiptsPaginated: { payment_receipts: components["schemas"]["PaymentReceiptObject"][]; meta: components["schemas"]["PaginationMeta"]; }; PaymentReceipt: { payment_receipt: components["schemas"]["PaymentReceiptObject"]; }; PaymentRequestCreateInput: { payment_request: { /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * Format: email * @description The customer's email address used for sending dunning notifications * @example dinesh@piedpiper.test */ email: string; /** @description A list of Nozle IDs for the customer's overdue invoices to start the dunning process */ invoice_ids: string[]; /** @description Optional payment method to use for processing the payment request. */ payment_method?: components["schemas"]["PaymentMethodReference"]; }; }; PaymentRequest: { payment_request: components["schemas"]["PaymentRequestObject"]; }; PaymentCreateInput: { payment: { /** * @description Unique identifier assigned to the invoice * @example 486b147a-02a1-4ccf-8603-f3541fc25e7a */ invoice_id: string; /** * @description The payment amount in cents * @example 100 */ amount_cents: number; /** * @description Reference for the payment * @example ref1 */ reference: string; /** * Format: date * @description The date the payment was made * @example 2025-02-20 */ paid_at?: string; }; }; Payment: { payment: components["schemas"]["PaymentObject"]; }; MinimumCommitmentObject: { /** * Format: uuid * @description Unique identifier of the minimum commitment, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The unique code representing the plan to be attached to the customer. * @example premium */ plan_code?: string; /** * @description The type of commitment. The only value is `minimum_commitment`. * @example minimum_commitment * @enum {string} */ commitment_type?: "minimum_commitment"; /** * @description The amount of the minimum commitment in cents. * @example 100000 */ amount_cents: number; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. * @example Minimum Commitment (C1) */ invoice_display_name?: string; /** * @description The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly` or `weekly`. * @example monthly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * Format: date-time * @description The date and time when the minimum commitment was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created. * @example 2022-04-29T08:59:51Z */ created_at: string; /** * Format: date-time * @description The date and time when the minimum commitment was updated. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created. * @example 2022-04-29T08:59:51Z */ updated_at?: string; /** @description All taxes applied to the minimum commitment. */ taxes?: components["schemas"]["TaxObject"][]; } | null; /** * @description Specifies the pricing model used for the calculation of the final fee. It can be any of the following values: * - [`dynamic`](https://docs.nozle.dev/guides/billing) * - [`graduated_percentage`](https://docs.nozle.dev/guides/billing) * - [`graduated`](https://docs.nozle.dev/guides/billing) * - [`package`](https://docs.nozle.dev/guides/billing) * - [`percentage`](https://docs.nozle.dev/guides/billing) * - [`standard`](https://docs.nozle.dev/guides/billing) * - [`volume`](https://docs.nozle.dev/guides/billing) * @enum {string} */ ChargeModelEnum: "dynamic" | "graduated" | "graduated_percentage" | "package" | "percentage" | "standard" | "volume"; ChargeProperties: { /** * @deprecated * @description The list of event properties that are used to group the events on the invoice for a `standard` charge model. * **DEPRECATED** Replaced by `pricing_group_keys`. * @example [ * "agent_name" * ] */ grouped_by?: string[]; /** * @description The list of event properties that are used to group the events on the invoice. * @example [ * "agent_name" * ] */ pricing_group_keys?: string[]; /** @description Graduated ranges, sorted from bottom to top tiers, used for a `graduated` charge model. */ graduated_ranges?: { /** * @description Specifies the lower value of a tier for a `graduated` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values. * @example 0 */ from_value: number; /** * @description Specifies the highest value of a tier for a `graduated` charge model. * - This value must be higher than the from_value of the same tier. * - This value must be null for the last tier. * @example 10 */ to_value: number | null; /** * @description The flat amount for a whole tier, excluding tax, for a `graduated` charge model. It is expressed as a decimal value. * @example 10 */ flat_amount: string; /** * @description The unit price, excluding tax, for a specific tier of a `graduated` charge model. It is expressed as a decimal value. * @example 0.5 */ per_unit_amount: string; }[]; /** @description Graduated percentage ranges, sorted from bottom to top tiers, used for a `graduated_percentage` charge model. */ graduated_percentage_ranges?: { /** * @description Specifies the lower value of a tier for a `graduated_percentage` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values. * @example 0 */ from_value: number; /** * @description Specifies the highest value of a tier for a `graduated_percentage` charge model. * - This value must be higher than the from_value of the same tier. * - This value must be null for the last tier. * @example 10 */ to_value: number | null; /** * Format: ^[0-9]+.?[0-9]*$ * @description The percentage rate that is applied to the amount of each transaction in the tier for a `graduated_percentage` charge model. It is expressed as a decimal value. * @example 1 */ rate: string; /** * Format: ^[0-9]+.?[0-9]*$ * @description The flat amount for a whole tier, excluding tax, for a `graduated_percentage` charge model. It is expressed as a decimal value. * @example 10 */ flat_amount: string; }[]; /** * @description - The unit price, excluding tax, for a `standard` charge model. It is expressed as a decimal value. * - The amount, excluding tax, for a complete set of units in a `package` charge model. It is expressed as a decimal value. * @example 30 */ amount?: string; /** * @description The quantity of units that are provided free of charge for each billing period in a `package` charge model. This field specifies the number of units that customers can use without incurring any additional cost during each billing cycle. * @example 100 */ free_units?: number; /** * @description The quantity of units included in each pack or set for a `package` charge model. It indicates the number of units that are bundled together as a single package or set within the pricing structure. * @example 1000 */ package_size?: number; /** * @description The percentage rate that is applied to the amount of each transaction for a `percentage` charge model. It is expressed as a decimal value. * @example 1 */ rate?: string; /** * @description The fixed fee that is applied to each transaction for a `percentage` charge model. It is expressed as a decimal value. * @example 0.5 */ fixed_amount?: string; /** * @description The count of transactions that are not impacted by the `percentage` rate and fixed fee in a percentage charge model. This field indicates the number of transactions that are exempt from the calculation of charges based on the specified percentage rate and fixed fee. * @example 5 */ free_units_per_events?: number | null; /** * @description The transaction amount that is not impacted by the `percentage` rate and fixed fee in a percentage charge model. This field indicates the portion of the transaction amount that is exempt from the calculation of charges based on the specified percentage rate and fixed fee. * @example 500 */ free_units_per_total_aggregation?: string | null; /** * Format: ^[0-9]+.?[0-9]*$ * @description Specifies the maximum allowable spending for a single transaction. Working as a transaction cap. * @example 3.75 */ per_transaction_max_amount?: string | null; /** * Format: ^[0-9]+.?[0-9]*$ * @description Specifies the minimum allowable spending for a single transaction. Working as a transaction floor. * @example 1.75 */ per_transaction_min_amount?: string | null; /** @description Volume ranges, sorted from bottom to top tiers, used for a `volume` charge model. */ volume_ranges?: { /** * @description Specifies the lower value of a tier for a `volume` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values. * @example 0 */ from_value: number; /** * @description Specifies the highest value of a tier for a `volume` charge model. * - This value must be higher than the `from_value` of the same tier. * - This value must be `null` for the last tier. * @example 10 */ to_value: number | null; /** * @description The flat amount for a whole tier, excluding tax, for a `volume` charge model. It is expressed as a decimal value. * @example 10 */ flat_amount: string; /** * @description The unit price, excluding tax, for a specific tier of a `volume` charge model. It is expressed as a decimal value. * @example 0.5 */ per_unit_amount: string; }[]; }; ChargeObjectProperties: components["schemas"]["ChargeProperties"] & { /** * @description Groups usage into sub-items on invoices for display only, without affecting pricing or aggregation. * @example [ * { * "value": "region", * "options": { * "display_in_invoice": true * } * } * ] */ presentation_group_keys?: { /** * @description The event property to group by. * @example region */ value?: string; options?: { /** @example true */ display_in_invoice?: boolean; }; }[]; }; /** @description Values used to apply differentiated pricing based on additional event properties. */ ChargeFilterObject: { /** * Format: uuid * @description Unique identifier of the charge filter. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Code of the charge the filter belongs to. * @example api_requests_charge */ charge_code: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name. * @example AWS */ invoice_display_name: string | null; /** @description List of all thresholds utilized for calculating the charge. */ properties: components["schemas"]["ChargeProperties"]; /** * @description List of possible filter values. The key and values must match one of the feature filters. * @example { * "region": [ * "us-east-1" * ] * } */ values: { [key: string]: string[]; }; }; ChargeObject: { /** * Format: uuid * @description Unique identifier of charge, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the feature created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ feature_id: string; /** * @description Unique code identifying the charge within the plan. * @example api_requests_charge */ code?: string | null; /** * @description Unique code identifying a feature. * @example requests */ feature_code: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string | null; /** * Format: date-time * @description The date and time when the charge was created. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2022-09-14T16:35:31Z */ created_at: string; charge_model: components["schemas"]["ChargeModelEnum"]; /** * @description This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to `false`, the charge is due and invoiced at the end of each billing period. * @example true */ pay_in_advance: boolean; /** * @description This field specifies whether the charge should be included in a proper invoice. If set to `false`, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`. * @example true */ invoiceable: boolean; /** * @description This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`. * This field determines whether and when the charge fee should be included in * the invoice. If `null`, no invoice will be issued for this charge fee. * If `invoice`, an invoice will be generated at the end of the period, * consolidating all charge fees with a succeeded payment status. * @example invoice * @enum {string|null} */ regroup_paid_fees: null | "invoice"; /** * @description Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - If not defined in the request, default value is `false`. * @example false */ prorated: boolean; /** * @description The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period. * @example 1200 */ min_amount_cents: number; /** @description List of all thresholds utilized for calculating the charge. */ properties: components["schemas"]["ChargeObjectProperties"]; /** @description List of filters used to apply differentiated pricing based on additional event properties. */ filters: components["schemas"]["ChargeFilterObject"][]; /** @description All taxes applied to the charge. */ taxes?: components["schemas"]["TaxObject"][]; /** @description The pricing unit applied to the charge. */ applied_pricing_unit?: { /** * @description The code of the pricing unit. * @example unit_code */ code: string; /** * @description The conversion rate from pricing units to the plan's currency. * @example 0.5 */ conversion_rate: string; } | null; /** * @description Specifies whether the charge accepts a target wallet for prepaid credits deduction. * @example false */ accepts_target_wallet?: boolean | null; /** * Format: uuid * @description Unique identifier of the parent charge (if this is an override). * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ parent_id?: string | null; }; FixedChargeProperties: { /** * @description - The unit price, excluding tax, for a `standard` charge model. It is expressed as a decimal value. * - The amount, excluding tax, for a complete set of units in a `package` charge model. It is expressed as a decimal value. * @example 30 */ amount?: string; /** @description Graduated ranges, sorted from bottom to top tiers, used for a `graduated` charge model. */ graduated_ranges?: { /** * @description Specifies the lower value of a tier for a `graduated` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values. * @example 0 */ from_value: number; /** * @description Specifies the highest value of a tier for a `graduated` charge model. * - This value must be higher than the from_value of the same tier. * - This value must be null for the last tier. * @example 10 */ to_value: number | null; /** * @description The flat amount for a whole tier, excluding tax, for a `graduated` charge model. It is expressed as a decimal value. * @example 10 */ flat_amount: string; /** * @description The unit price, excluding tax, for a specific tier of a `graduated` charge model. It is expressed as a decimal value. * @example 0.5 */ per_unit_amount: string; }[]; /** @description Volume ranges, sorted from bottom to top tiers, used for a `volume` charge model. */ volume_ranges?: { /** * @description Specifies the lower value of a tier for a `volume` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values. * @example 0 */ from_value: number; /** * @description Specifies the highest value of a tier for a `volume` charge model. * - This value must be higher than the `from_value` of the same tier. * - This value must be `null` for the last tier. * @example 10 */ to_value: number | null; /** * @description The flat amount for a whole tier, excluding tax, for a `volume` charge model. It is expressed as a decimal value. * @example 10 */ flat_amount: string; /** * @description The unit price, excluding tax, for a specific tier of a `volume` charge model. It is expressed as a decimal value. * @example 0.5 */ per_unit_amount: string; }[]; }; FixedChargeObject: { /** * Format: uuid * @description Unique identifier of the fixed charge, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the add-on associated with this fixed charge. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ add_on_id: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup fee */ invoice_display_name: string; /** * @description Unique code used to identify the add-on. * @example setup_fee */ add_on_code: string; /** * Format: date-time * @description The date and time when the fixed charge was created. It is expressed in UTC format according to the ISO 8601 datetime standard. * @example 2023-06-27T19:43:42Z */ created_at: string; /** * @description Unique code for the fixed charge. * @example setup_fee */ code: string; /** * @description The charge model for the fixed charge. Only `standard`, `graduated`, and `volume` models are supported for fixed charges. * @example standard * @enum {string} */ charge_model: "standard" | "graduated" | "volume"; /** * @description This field determines the billing timing for this fixed charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. * @example false */ pay_in_advance: boolean; /** * @description Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - If not defined in the request, default value is `false`. * @example false */ prorated: boolean; /** @description List of all thresholds utilized for calculating the fixed charge. */ properties: components["schemas"]["FixedChargeProperties"]; /** * @description The number of units for the fixed charge. * * When retrieved through a subscription-scoped endpoint (e.g. `GET /subscriptions/{external_id}/fixed_charges`), this reflects the per-subscription unit override when one exists, and falls back to the plan-level units otherwise. Plan-scoped endpoints always return the plan-level units. * @example 1 */ units: number; /** * Format: uuid * @description Unique identifier of the parent fixed charge (for plan versions). * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ parent_id?: string | null; /** @description List of taxes applied to the fixed charge. */ taxes?: components["schemas"]["TaxObject"][]; }; PlanEntitlementPrivilegeObject: components["schemas"]["FeaturePrivilegeObject"] & { /** * @description Value assigned to this privilege in the entitlement. Type depends on the privilege's value_type. * @example 10 */ value: number | boolean | string; }; PlanEntitlementObject: { /** * Format: uuid * @description Unique identifier of the feature. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ feature_id: string; /** * @description `boolean` is an on/off capability. `config` carries privilege values (for example a support tier). `metered` is counted usage with an optional `usage_limit`. * @example config * @enum {string} */ feature_type: "boolean" | "config" | "metered"; /** * @description Usage allowed per period for a metered feature. `null` means no limit is set (and always `null` for boolean and config features). * @example null */ usage_limit: number | null; /** * @description For a metered feature, `true` blocks usage over `usage_limit`. `null` for boolean and config features. * @example null */ hard_limit: boolean | null; /** * @description Unique code used to identify the feature. Max 255 characters. * @example seats */ code: string; /** * @description Name of the feature. Max 255 characters. * @example Number of seats */ name: string | null; /** * @description Description of the feature. Max 600 characters. * @example Number of users of the account */ description: string | null; /** * @description Privileges associated with this feature. Each privilege must have a value assigned. Always an empty array for metered features. * @example [ * { * "code": "max", * "name": "Maximum", * "value_type": "integer", * "config": {}, * "value": 10 * }, * { * "code": "max_admins", * "name": "Max Admins", * "value_type": "integer", * "config": {}, * "value": 5 * }, * { * "code": "root", * "name": "Allow root user", * "value_type": "boolean", * "config": {}, * "value": true * }, * { * "code": "provider", * "name": "SSO Provider", * "value_type": "select", * "value": "google", * "config": { * "select_options": [ * "google", * "microsoft" * ] * } * } * ] */ privileges: components["schemas"]["PlanEntitlementPrivilegeObject"][]; }; PlanEntitlement: { entitlement: components["schemas"]["PlanEntitlementObject"]; }; /** * @description A plan. This is the object returned by `GET /plans`, `GET /plans/{code}` and the plan write endpoints. * * With a publishable `pk_` key, `GET /plans` and `GET /plans/{code}` return this whole object, including prices, charges, taxes, minimums, credit grants and `metadata`. Nothing is filtered or redacted. See "Publishable keys" on those operations. * * `charges`, `entitlements`, `usage_thresholds`, `applicable_usage_thresholds`, `taxes`, `credit_grant_rules` and `credit_pool_policies` are always present in a plan returned by the plan endpoints. They are empty arrays when the plan has none. */ PlanObject: { /** * Format: uuid * @description Unique identifier of the plan created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The name of the plan. * @example Startup */ name: string; /** * @description Specifies the name that will be displayed on an invoice. `null` when no value is set; the name of the plan is then used as the display name. * @example Startup plan */ invoice_display_name: string | null; /** * Format: date-time * @description The date and time when the plan was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the plan was initially created. * @example 2023-06-27T19:43:42Z */ created_at: string; /** * @description The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance. * @example startup */ code: string; /** * @description The version of the plan code this plan is. A plan is version 1 until its pricing is changed while customers pay for it; that change saves version 2, and so on. Every version keeps the code. See [Plan versioning](/guides/billing/plan-versions). * @example 2 */ version?: number; /** * @description Whether new subscriptions to the code get this version. `GET /plans` and `GET /plans/{code}` return the current version unless a secret key asks for another one with `version`. * @example true */ is_current?: boolean; /** * @description The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly` or `weekly`. * @example monthly * @enum {string} */ interval: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description The description on the plan. `null` when none was set. * @example For teams that need more than the free tier. */ description: string | null; /** * @description The base cost of the plan per `interval`, excluding any applicable taxes, in the smallest unit of `amount_currency` (cents for USD, so `1499` is 14.99 USD). It is `0` for a free or pure pay-as-you-go plan. Usage-based prices are not included here, they are in `charges`. * @example 10000 */ amount_cents: number; /** * @description The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. * @example USD */ amount_currency: components["schemas"]["Currency"]; /** * @description The duration in days during which the base cost of the plan is offered for free. `null` when the plan has no trial. A plan with a trial is still returned by the public catalog. * @example 5 */ trial_period: number | null; /** * @description This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the plan is pay-in-arrears and the base cost is due at the end of each billing period. Pay-in-arrears plans are also returned by the public catalog. * @example true */ pay_in_advance: boolean; /** * @description This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. * @example null */ bill_charges_monthly: boolean | null; /** * @description This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. * @example null */ bill_fixed_charges_monthly: boolean | null; /** * @description Core 11.16.0. Days after the unpaid invoice of an automatic upgrade at the plan's MRR limit before the end action, 0 to 90 (`0` acts at once). Read for Nozle's own plans; the dunning policy of your customers reads `unpaid_invoice_grace_days`. Editing it never creates a new plan version. Out of range: `422` `value_is_out_of_range`. * @example 7 */ limit_grace_days?: number; /** * @description Core 11.16.0. Days between day 0 of an unpaid invoice of this plan and the end action of its [dunning policy](/guides/billing/dunning), 0 to 90 (`0` acts at once). Editing it never creates a new plan version; new versions and the other currencies of a plan family copy it. Out of range: `422` `value_is_out_of_range`. * @example 7 */ unpaid_invoice_grace_days?: number; /** * @description Core 11.16.0. The dunning campaign the plan's unpaid invoices follow, before the customer's and the billing entity's. `null` unlinks it. An unknown code returns `404` `dunning_campaign_not_found`. Editing it never creates a new plan version. * @example block_after_grace */ dunning_campaign_code?: string | null; /** * Format: uuid * @description Identifier of the parent plan when this plan is a per-customer override of another plan. `null` for a regular plan. Override plans are not returned by `GET /plans` or `GET /plans/{code}`, so it is `null` there. * @example null */ parent_id: string | null; /** * @description Code of the plan family the plan belongs to. A plan family groups the billing intervals and currencies of one offer (for example "Pro" monthly and yearly, in USD and EUR). `null` for a per-customer override plan, which has no family. * @example startup */ plan_family_code?: string | null; /** @description Core 11.10.0. The plan's family, on every plan of a family in `GET /plans` and `GET /plans/{code}`. Absent for a plan without a family, and for a publishable key reading a plan of a family hidden from the pricing table with `GET /plans/{code}`. See [Multi-currency pricing](/guides/billing/multi-currency-pricing). */ family?: { /** * @description Code of the plan family. * @example pro */ code: string; /** * @description The currencies the family's current plans sell, in display order. * @example [ * "USD", * "EUR" * ] */ currencies: string[]; /** * @description The currency the pricing table shows first. Always one of `currencies`. * @example USD */ default_currency: string; }; /** @description Core 11.10.0. Every current plan of the family, in every interval and currency, plans pending deletion left out. Present when `family` is. One plan per interval and currency. */ prices?: { /** * @description ISO 4217 code of the plan. * @example EUR */ currency: string; /** * @example monthly * @enum {string} */ interval: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description Code of the plan that sells this interval and currency. Use it, or `plan_family_code` with `interval` and `currency`, to check out. * @example pro_eur */ plan_code: string; /** * @description Base price per interval, in the minor unit of `currency`. * @example 900 */ amount_cents: number; }[]; /** * @description `true` when deletion of the plan was requested and is still being processed in the background. The plan is going away and should not be offered to new customers; `GET /plans` still lists it until the deletion finishes. Filter on `pending_deletion` when you build a pricing page. * @example false */ pending_deletion: boolean; /** @description Minimum commitment of the plan. The key is omitted, not `null`, when the plan has no minimum commitment. */ minimum_commitment?: components["schemas"]["MinimumCommitmentObject"]; /** * @description Usage-based charges for this plan, one per feature. Empty array when the plan has only a base price. * @example [ * { * "nozle_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", * "feature_code": "requests", * "created_at": "2023-06-27T19:43:42Z", * "charge_model": "package", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "regroup_paid_fees": null, * "prorated": false, * "min_amount_cents": 3000, * "properties": { * "amount": "30", * "free_units": 100, * "package_size": 1000 * }, * "filters": [] * }, * { * "nozle_id": "1a901a90-1a90-1a90-1a90-1a901a901a92", * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a92", * "feature_code": "cpu", * "created_at": "2023-06-27T19:43:42Z", * "charge_model": "graduated", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "regroup_paid_fees": null, * "prorated": false, * "min_amount_cents": 0, * "properties": { * "graduated_ranges": [ * { * "from_value": 0, * "to_value": 10, * "flat_amount": "10", * "per_unit_amount": "0.5" * }, * { * "from_value": 11, * "to_value": null, * "flat_amount": "0", * "per_unit_amount": "0.4" * } * ] * }, * "filters": [] * }, * { * "nozle_id": "1a901a90-1a90-1a90-1a90-1a901a901a93", * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a93", * "feature_code": "seats", * "created_at": "2023-06-27T19:43:42Z", * "charge_model": "standard", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": true, * "regroup_paid_fees": null, * "prorated": false, * "min_amount_cents": 0, * "properties": {}, * "filters": [ * { * "invoice_display_name": "Europe", * "properties": { * "amount": "10" * }, * "values": { * "region": [ * "Europe" * ] * } * }, * { * "invoice_display_name": "USA", * "properties": { * "amount": "5" * }, * "values": { * "region": [ * "USA" * ] * } * }, * { * "invoice_display_name": "Africa", * "properties": { * "amount": "8" * }, * "values": { * "region": [ * "Africa" * ] * } * } * ] * }, * { * "nozle_id": "1a901a90-1a90-1a90-1a90-1a901a901a94", * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a94", * "feature_code": "storage", * "created_at": "2023-06-27T19:43:42Z", * "charge_model": "volume", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "regroup_paid_fees": null, * "prorated": false, * "min_amount_cents": 0, * "properties": { * "volume_ranges": [ * { * "from_value": 0, * "to_value": 100, * "flat_amount": "0", * "per_unit_amount": "0" * }, * { * "from_value": 101, * "to_value": null, * "flat_amount": "0", * "per_unit_amount": "0.5" * } * ] * }, * "filters": [] * }, * { * "nozle_id": "1a901a90-1a90-1a90-1a90-1a901a901a95", * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a95", * "feature_code": "payments", * "created_at": "2023-06-27T19:43:42Z", * "charge_model": "percentage", * "invoiceable": false, * "invoice_display_name": "Setup", * "pay_in_advance": true, * "regroup_paid_fees": "invoice", * "prorated": false, * "min_amount_cents": 0, * "properties": { * "rate": "1", * "fixed_amount": "0.5", * "free_units_per_events": 5, * "free_units_per_total_aggregation": "500" * }, * "filters": [] * } * ] */ charges?: components["schemas"]["ChargeObject"][]; /** * @description List of fixed charges for this plan. Returned by single-plan responses (`GET /plans/{code}`, create, update, delete). It is not included in the items of `GET /plans`. * @example [ * { * "nozle_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", * "add_on_id": "2b802b80-2b80-2b80-2b80-2b802b802b80", * "code": "setup_fee", * "invoice_display_name": "Setup Fee", * "add_on_code": "setup", * "created_at": "2026-01-15T10:30:00Z", * "charge_model": "standard", * "pay_in_advance": true, * "prorated": false, * "properties": { * "amount": "500" * }, * "units": 1, * "parent_id": null, * "taxes": [ * { * "nozle_id": "3c703c70-3c70-3c70-3c70-3c703c703c70", * "name": "VAT", * "code": "vat_20", * "rate": 20, * "description": "Standard VAT rate", * "applied_to_organization": true, * "created_at": "2026-01-01T00:00:00Z" * } * ] * }, * { * "nozle_id": "4d604d60-4d60-4d60-4d60-4d604d604d60", * "add_on_id": "5e505e50-5e50-5e50-5e50-5e505e505e50", * "code": "support_tier", * "invoice_display_name": "Support Tier", * "add_on_code": "premium_support", * "created_at": "2026-01-15T10:30:00Z", * "charge_model": "graduated", * "pay_in_advance": false, * "prorated": true, * "properties": { * "graduated_ranges": [ * { * "from_value": 0, * "to_value": 10, * "per_unit_amount": "5", * "flat_amount": "200" * }, * { * "from_value": 11, * "to_value": null, * "per_unit_amount": "1", * "flat_amount": "300" * } * ] * }, * "units": 1, * "parent_id": null, * "taxes": [] * }, * { * "nozle_id": "6f406f40-6f40-6f40-6f40-6f406f406f40", * "add_on_id": "7a307a30-7a30-7a30-7a30-7a307a307a30", * "code": "storage", * "invoice_display_name": "Storage Allocation", * "add_on_code": "cloud_storage", * "created_at": "2026-01-15T10:30:00Z", * "charge_model": "volume", * "pay_in_advance": false, * "prorated": false, * "properties": { * "volume_ranges": [ * { * "from_value": 0, * "to_value": 100, * "per_unit_amount": "2", * "flat_amount": "1" * }, * { * "from_value": 101, * "to_value": null, * "per_unit_amount": "1", * "flat_amount": "0" * } * ] * }, * "units": 50, * "parent_id": null, * "taxes": [] * } * ] */ fixed_charges?: components["schemas"]["FixedChargeObject"][]; /** @description Taxes applied to the plan itself. Charges, fixed charges and the minimum commitment carry their own `taxes`. */ taxes?: components["schemas"]["TaxObject"][]; /** @description Usage thresholds that trigger a progressive billing invoice on this plan. */ usage_thresholds?: components["schemas"]["UsageThresholdObject"][]; /** @description Usage thresholds that apply when this plan is used. Same as `usage_thresholds` for a regular plan; for an override plan it is the parent plan's list. Entries have no `nozle_id` or timestamps. */ applicable_usage_thresholds?: components["schemas"]["ApplicableUsageThreshold"][]; /** @description Feature entitlements of the plan (boolean, config and metered features) with their privilege values. Each item is the entitlement itself; it is not wrapped in an `entitlement` key. */ entitlements?: components["schemas"]["PlanEntitlementObject"][]; /** @description Active credit grant rules. Each rule grants credits of one credit system to subscribers of the plan. */ credit_grant_rules?: components["schemas"]["PlanCreditGrantRuleObject"][]; /** @description Active credit pool policies. Each says which credit pool an entity of this plan spends from, for one credit system. */ credit_pool_policies?: components["schemas"]["PlanCreditPoolPolicyObject"][]; /** @description Custom key-value pairs set on the plan. The key is omitted when the plan has no metadata. With a publishable key, metadata is readable by anyone who has the key. */ metadata?: components["schemas"]["MetadataObject"]; }; PlanCreditGrantRuleObject: { /** * Format: uuid * @description Unique identifier of the credit grant rule. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Identifier of the plan the rule belongs to. * @example 1a901a90-1a90-1a90-1a90-1a901a901a91 */ plan_id: string; /** * @description Code of the plan the rule belongs to. * @example pro */ plan_code: string; /** * Format: uuid * @description Identifier of the credit system that is granted. * @example 1a901a90-1a90-1a90-1a90-1a901a901a92 */ credit_system_id: string; /** * @description Code of the credit system that is granted. * @example ai_credits */ credit_system_code: string; /** * @description Credits granted each time the rule runs, as an exact decimal string (for example `500.0`). It is in credits, not cents. * @example 500.0 */ amount: string; /** * @description How often the grant repeats. `lifetime` grants once, when the subscription starts. * @example month * @enum {string} */ interval: "month" | "year" | "lifetime"; /** * @description Number of `interval` periods between grants. * @example 1 */ interval_count: number; /** * @description `customer` grants to the customer's shared pool. `entity` grants to each entity of the customer. * @example entity * @enum {string} */ scope: "customer" | "entity"; /** * @description What an entity that joins mid-period receives. `null` when `scope` is `customer`. * @example full_grant * @enum {string|null} */ entity_join_policy: "full_grant" | "prorated" | "next_period" | null; /** * @description What happens to the plan grant when an entity leaves. `null` when `scope` is `customer`. * @example expire_plan_grant * @enum {string|null} */ entity_leave_policy: "expire_plan_grant" | null; /** * @description Credits granted on an upgrade to this plan. * @example grant_difference * @enum {string} */ upgrade_policy: "grant_difference"; /** * @description When a downgrade to this plan changes the grant. * @example next_period * @enum {string} */ downgrade_policy: "next_period"; /** * @description Plan responses list only `active` rules. * @example active * @enum {string} */ status: "active" | "archived"; /** * Format: date-time * @description When the rule was created, in UTC (ISO 8601). * @example 2026-01-15T10:00:00Z */ created_at: string; /** * Format: date-time * @description When the rule was last updated, in UTC (ISO 8601). * @example 2026-01-15T10:00:00Z */ updated_at: string; }; PlanCreditPoolPolicyObject: { /** * Format: uuid * @description Unique identifier of the credit pool policy. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Identifier of the plan the policy belongs to. * @example 1a901a90-1a90-1a90-1a90-1a901a901a91 */ plan_id: string; /** * @description Code of the plan the policy belongs to. * @example pro */ plan_code: string; /** * Format: uuid * @description Identifier of the credit system the policy applies to. * @example 1a901a90-1a90-1a90-1a90-1a901a901a92 */ credit_system_id: string; /** * @description Code of the credit system the policy applies to. * @example ai_credits */ credit_system_code: string; /** * @description `entity_only` spends only entity-owned credits. `entity_then_customer` spends entity credits first, then the shared customer pool. `customer_only` records entity attribution but spends only the shared customer pool. * @example entity_only * @enum {string} */ policy: "entity_only" | "entity_then_customer" | "customer_only"; /** * @description Plan responses list only `active` policies. * @example active * @enum {string} */ status: "active" | "archived"; /** * Format: date-time * @description When the policy was created, in UTC (ISO 8601). * @example 2026-01-15T10:00:00Z */ created_at: string; /** * Format: date-time * @description When the policy was last updated, in UTC (ISO 8601). * @example 2026-01-15T10:00:00Z */ updated_at: string; }; PlansPaginated: { plans: components["schemas"]["PlanObject"][]; /** @description The plan families of the returned plans, ordered by pricing position. A publishable key, or `include_hidden=false`, leaves out families and features hidden from the pricing table. */ families?: { code?: string; name?: string; description?: string | null; show_on_pricing?: boolean; pricing_position?: number | null; pricing_highlighted?: boolean; badge_text?: string | null; cta_text?: string | null; /** @description Codes of the family's plans in the listed currency (every plan of the family for a secret key without `currency`). A publishable key does not receive the codes of plans pending deletion. */ plan_codes?: string[]; /** * @description Core 11.10.0. The currencies the family's current plans sell, in display order. * @example [ * "USD", * "EUR" * ] */ currencies?: string[]; /** * @description Core 11.10.0. The currency the pricing table shows first. Always one of `currencies`. * @example USD */ default_currency?: string; features?: { code?: string; name?: string; description?: string | null; show_on_pricing?: boolean; show_description?: boolean; display_position?: number | null; }[]; }[]; meta: components["schemas"]["PaginationMeta"] & { /** * @description The appearance saved for the organization on the dashboard page Developers > Customize SDK, which the React SDK components apply automatically. `{}` when none is saved. Keys are `theme`, `variables`, `planCardLayout`, `pricingTable`, `hideBranding` and `components`, where `components` maps an SDK component name (such as `UsageMeter`) to its own `theme`, `variables`, `planCardLayout` and `pricingTable`. Returned for publishable and secret keys on this list endpoint only, not on `GET /plans/{code}`. * @example { * "theme": "nozle", * "variables": { * "colorHighlight": "#16a34a" * }, * "planCardLayout": "panel", * "pricingTable": { * "highlightStyle": "outline", * "annualDiscountLabel": "Save 20%", * "showToggle": true * }, * "components": { * "UsageMeter": { * "variables": { * "colorPrimary": "#e11d48" * } * } * } * } */ sdk_appearance?: { [key: string]: unknown; }; /** * @description Whether the SDK components show "Powered by Nozle". `false` only when the organization's Nozle plan lets it remove the branding and `sdk_appearance.hideBranding` is `true`. Invoice, credit note and payment receipt PDFs always show it. Returned for publishable keys only. * @example true */ nozle_branding?: boolean; }; }; /** @description Minimum commitment for this plan. */ MinimumCommitmentInput: { /** * @description The amount of the minimum commitment in cents. * @example 100000 */ amount_cents: number; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. * @example Minimum Commitment (C1) */ invoice_display_name?: string; tax_codes?: components["schemas"]["TaxCodes"]; } | null; /** @description Values used to apply differentiated pricing based on additional event properties. */ ChargeFilterInput: { /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name. * @example AWS */ invoice_display_name?: string | null; /** @description List of all thresholds utilized for calculating the charge. */ properties: components["schemas"]["ChargeProperties"]; /** * @description List of possible filter values. The key and values must match one of the feature filters. * @example { * "region": [ * "us-east-1" * ] * } */ values: { [key: string]: string[]; }; }; UsageThresholdInput: { /** * @description The display name of the usage threshold. * @example Threshold 1 */ threshold_display_name?: string | null; /** * @description The amount to reach to trigger a `progressive_billing` invoice. * @example 10000 */ amount_cents: number; /** * @description This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount. * @default false * @example true */ recurring: boolean; }; PlanCreateInput: { plan: { /** * @description The name of the plan. * @example Startup */ name: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name. * @example Startup plan */ invoice_display_name?: string | null; /** * @description The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance. * @example startup */ code: string; /** * @description The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly`, or `weekly`. * @example monthly * @enum {string} */ interval: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description The description on the plan. * @example Plan for early stage startups. */ description?: string | null; /** * @description Code of the plan family the plan belongs to, for example the monthly and yearly versions of one plan. Without it, or with a code that does not exist yet, the call creates a new family for the plan. A family holds at most one current plan per `interval` and `amount_currency` (Core 11.10.0; before, one currency per family); otherwise the call returns `422` with the error `plan_family_interval_already_exist` on `interval`. A plan in a new currency adds that currency to the family. In a family sold in several currencies, the plans of one interval may differ only in money (`plan_family_variant_mismatch`); see [Multi-currency pricing](/guides/billing/multi-currency-pricing). A plan that joins a family that already has plans takes the family's features and privileges. * @example startup */ plan_family_code?: string | null; /** * @description Whether a plan family that this call creates is shown on the pricing table and in the publishable-key catalog (`GET /plans`, `GET /plans/{code}`). Defaults to `true`; send `false` to create a plan that is not shown yet. A family that the plan joins keeps its own visibility. GraphQL `createPlan` and `updatePlan` take the same field as `showOnPricing`. * @default true */ show_on_pricing: boolean; /** * @description The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan. * @example 10000 */ amount_cents: number; /** * @description The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. * @example USD */ amount_currency: components["schemas"]["Currency"]; /** * @description The duration in days during which the base cost of the plan is offered for free. * @example 5 */ trial_period?: number | null; /** * @description This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period. * @example true */ pay_in_advance: boolean; /** * @description This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is `yearly` or `semiannual`. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. * @example null */ bill_charges_monthly?: boolean | null; /** * @description This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is `yearly` or `semiannual`. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. * @example null */ bill_fixed_charges_monthly?: boolean | null; /** * @description Core 11.16.0. Days after the unpaid invoice of an automatic upgrade at the plan's MRR limit before the end action, 0 to 90 (`0` acts at once). Read for Nozle's own plans; the dunning policy of your customers reads `unpaid_invoice_grace_days`. Editing it never creates a new plan version. Out of range: `422` `value_is_out_of_range`. * @default 7 * @example 7 */ limit_grace_days: number; /** * @description Core 11.16.0. Days between day 0 of an unpaid invoice of this plan and the end action of its [dunning policy](/guides/billing/dunning), 0 to 90 (`0` acts at once). Editing it never creates a new plan version; new versions and the other currencies of a plan family copy it. Out of range: `422` `value_is_out_of_range`. * @default 7 * @example 7 */ unpaid_invoice_grace_days: number; /** * @description Core 11.16.0. The dunning campaign the plan's unpaid invoices follow, before the customer's and the billing entity's. `null` unlinks it. An unknown code returns `404` `dunning_campaign_not_found`. Editing it never creates a new plan version. * @example block_after_grace */ dunning_campaign_code?: string | null; tax_codes?: components["schemas"]["TaxCodes"]; minimum_commitment?: components["schemas"]["MinimumCommitmentInput"]; /** * @description Additional usage-based charges for this plan. * @example [ * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", * "charge_model": "package", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "regroup_paid_fees": null, * "prorated": false, * "min_amount_cents": 3000, * "properties": { * "amount": "30", * "free_units": 100, * "package_size": 1000 * }, * "tax_codes": [ * "french_standard_vat" * ] * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a92", * "charge_model": "graduated", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "prorated": false, * "min_amount_cents": 0, * "properties": { * "graduated_ranges": [ * { * "to_value": 10, * "from_value": 0, * "flat_amount": "10", * "per_unit_amount": "0.5" * }, * { * "to_value": null, * "from_value": 11, * "flat_amount": "0", * "per_unit_amount": "0.4" * } * ] * } * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a93", * "charge_model": "standard", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": true, * "prorated": false, * "min_amount_cents": 0, * "properties": {} * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a94", * "charge_model": "volume", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "prorated": false, * "min_amount_cents": 0, * "properties": { * "volume_ranges": [ * { * "from_value": 0, * "to_value": 100, * "flat_amount": "0", * "per_unit_amount": "0" * }, * { * "from_value": 101, * "to_value": null, * "flat_amount": "0", * "per_unit_amount": "0.5" * } * ] * } * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a95", * "charge_model": "percentage", * "invoiceable": false, * "invoice_display_name": "Setup", * "pay_in_advance": true, * "regroup_paid_fees": "invoice", * "prorated": false, * "min_amount_cents": 0, * "properties": { * "rate": "1", * "fixed_amount": "0.5", * "free_units_per_events": 5, * "free_units_per_total_aggregation": "500" * } * } * ] */ charges?: { /** * Format: uuid * @description Unique identifier of the feature created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ feature_id: string; /** * @description Unique code identifying the charge within the plan. * @example api_requests_charge */ code?: string; charge_model: components["schemas"]["ChargeModelEnum"]; /** * @description This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. * @example false */ pay_in_advance?: boolean; /** * @description This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`. * @example true */ invoiceable?: boolean; /** * @description This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`. * This field determines whether and when the charge fee should be included in * the invoice. If `null`, no invoice will be issued for this charge fee. * If `invoice`, an invoice will be generated at the end of the period, * consolidating all charge fees with a succeeded payment status. * @example invoice * @enum {string|null} */ regroup_paid_fees?: null | "invoice"; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string; /** * @description Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - If not defined in the request, default value is `false`. * @example false */ prorated?: boolean; /** * @description The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period. * @example 0 */ min_amount_cents?: number; /** @description List of all thresholds utilized for calculating the charge. */ properties?: components["schemas"]["ChargeObjectProperties"]; /** @description List of filters used to apply differentiated pricing based on additional event properties. */ filters?: components["schemas"]["ChargeFilterInput"][]; tax_codes?: components["schemas"]["TaxCodes"]; /** @description The pricing unit to apply to the charge. */ applied_pricing_unit?: { /** * @description The code of the pricing unit. * @example credits */ code?: string; /** * @description The conversion rate from pricing units to the plan's currency. * This rate determines how many currency units (in the plan's base currency) equal one pricing unit. * For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50. * @example 0.5 */ conversion_rate?: string; }; /** * @description Specifies whether the charge accepts a target wallet for prepaid credits deduction. * @example false */ accepts_target_wallet?: boolean | null; }[]; /** * @description Additional fixed charges for this plan. * @example [ * { * "add_on_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", * "code": "setup_fee", * "invoice_display_name": "Setup Fee", * "charge_model": "standard", * "pay_in_advance": true, * "prorated": false, * "properties": { * "amount": "500" * }, * "units": 1, * "tax_codes": [ * "french_standard_vat" * ] * }, * { * "add_on_id": "4d604d60-4d60-4d60-4d60-4d604d604d60", * "invoice_display_name": "Support Tier", * "charge_model": "graduated", * "pay_in_advance": false, * "prorated": true, * "properties": { * "graduated_ranges": [ * { * "from_value": 0, * "to_value": 10, * "per_unit_amount": "5", * "flat_amount": "200" * }, * { * "from_value": 11, * "to_value": null, * "per_unit_amount": "1", * "flat_amount": "300" * } * ] * }, * "units": 2 * }, * { * "add_on_id": "6f406f40-6f40-6f40-6f40-6f406f406f40", * "charge_model": "volume", * "properties": { * "volume_ranges": [ * { * "from_value": 0, * "to_value": 100, * "per_unit_amount": "2", * "flat_amount": "1" * }, * { * "from_value": 101, * "to_value": null, * "per_unit_amount": "1", * "flat_amount": "0" * } * ] * }, * "units": 50 * } * ] */ fixed_charges?: { /** * Format: uuid * @description Unique identifier of the add-on associated with this fixed charge. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ add_on_id: string; /** * @description Unique code for the fixed charge. If not provided, it will be automatically generated based on the add-on code. * @example setup_fee */ code?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup fee */ invoice_display_name?: string; /** * @description The number of units for the fixed charge. Defaults to 0 if not provided. * @default 0 * @example 1 */ units: number; /** * @description The charge model for the fixed charge. Only `standard`, `graduated`, and `volume` models are supported for fixed charges. * @example standard * @enum {string} */ charge_model: "standard" | "graduated" | "volume"; /** * @description This field determines the billing timing for this specific fixed charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. Defaults to `false` if not provided. * @default false * @example false */ pay_in_advance: boolean; /** * @description Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - Defaults to `false` if not provided. * * Note: Prorated fixed charges with `graduated` model and `pay_in_advance` are not allowed. * @default false * @example false */ prorated: boolean; /** @description List of all thresholds utilized for calculating the fixed charge. */ properties?: components["schemas"]["FixedChargeProperties"]; /** @description List of taxes applied to the fixed charge. */ tax_codes?: components["schemas"]["TaxCodes"]; }[]; /** @description List of usage thresholds to apply to the plan. */ usage_thresholds?: components["schemas"]["UsageThresholdInput"][]; metadata?: components["schemas"]["MetadataInput"]; }; }; Plan: { plan: components["schemas"]["PlanObject"]; }; PlanUpdateInput: { plan: { /** * @description The name of the plan. * @example Startup */ name?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name. * @example Startup plan */ invoice_display_name?: string | null; /** * @description The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance. * @example startup */ code?: string; /** * @description The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly`, or `weekly`. * @example monthly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description The description on the plan. * @example Plan for early stage startups. */ description?: string | null; /** * @description Code of the plan family the plan belongs to, for example the monthly and yearly versions of one plan. Without it, or with a code that does not exist yet, the call creates a new family for the plan. A family holds at most one current plan per `interval` and `amount_currency` (Core 11.10.0; before, one currency per family); otherwise the call returns `422` with the error `plan_family_interval_already_exist` on `interval`. A plan in a new currency adds that currency to the family. In a family sold in several currencies, the plans of one interval may differ only in money (`plan_family_variant_mismatch`); see [Multi-currency pricing](/guides/billing/multi-currency-pricing). A plan that joins a family that already has plans takes the family's features and privileges. * @example startup */ plan_family_code?: string | null; /** * @description Whether a plan family that this call creates is shown on the pricing table and in the publishable-key catalog (`GET /plans`, `GET /plans/{code}`). Defaults to `true`; send `false` to create a plan that is not shown yet. A family that the plan joins keeps its own visibility. GraphQL `createPlan` and `updatePlan` take the same field as `showOnPricing`. * @default true */ show_on_pricing: boolean; /** * @description The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan. * @example 10000 */ amount_cents?: number; /** * @description The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. * @example USD */ amount_currency?: components["schemas"]["Currency"]; /** * @description The duration in days during which the base cost of the plan is offered for free. * @example 5 */ trial_period?: number | null; /** * @description This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period. * @example true */ pay_in_advance?: boolean; /** * @description This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. * @example null */ bill_charges_monthly?: boolean | null; /** * @description This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is `yearly` or `semiannual`. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. * @example null */ bill_fixed_charges_monthly?: boolean | null; /** * @description Core 11.16.0. Days after the unpaid invoice of an automatic upgrade at the plan's MRR limit before the end action, 0 to 90 (`0` acts at once). Read for Nozle's own plans; the dunning policy of your customers reads `unpaid_invoice_grace_days`. Editing it never creates a new plan version. Out of range: `422` `value_is_out_of_range`. * @example 7 */ limit_grace_days?: number; /** * @description Core 11.16.0. Days between day 0 of an unpaid invoice of this plan and the end action of its [dunning policy](/guides/billing/dunning), 0 to 90 (`0` acts at once). Editing it never creates a new plan version; new versions and the other currencies of a plan family copy it. Out of range: `422` `value_is_out_of_range`. * @example 7 */ unpaid_invoice_grace_days?: number; /** * @description Core 11.16.0. The dunning campaign the plan's unpaid invoices follow, before the customer's and the billing entity's. `null` unlinks it. An unknown code returns `404` `dunning_campaign_not_found`. Editing it never creates a new plan version. * @example block_after_grace */ dunning_campaign_code?: string | null; tax_codes?: components["schemas"]["TaxCodes"]; minimum_commitment?: components["schemas"]["MinimumCommitmentInput"]; /** * @description Additional usage-based charges for this plan. * @example [ * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a91", * "charge_model": "package", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "prorated": false, * "min_amount_cents": 3000, * "properties": { * "amount": "30", * "free_units": 100, * "package_size": 1000 * }, * "tax_codes": [ * "french_standard_vat" * ] * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a92", * "charge_model": "graduated", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "prorated": false, * "min_amount_cents": 0, * "properties": { * "graduated_ranges": [ * { * "to_value": 10, * "from_value": 0, * "flat_amount": "10", * "per_unit_amount": "0.5" * }, * { * "to_value": null, * "from_value": 11, * "flat_amount": "0", * "per_unit_amount": "0.4" * } * ] * } * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a93", * "charge_model": "standard", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": true, * "regroup_paid_fees": null, * "prorated": false, * "min_amount_cents": 0, * "properties": {} * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a94", * "charge_model": "volume", * "invoiceable": true, * "invoice_display_name": "Setup", * "pay_in_advance": false, * "prorated": false, * "min_amount_cents": 0, * "properties": { * "volume_ranges": [ * { * "from_value": 0, * "to_value": 100, * "flat_amount": "0", * "per_unit_amount": "0" * }, * { * "from_value": 101, * "to_value": null, * "flat_amount": "0", * "per_unit_amount": "0.5" * } * ] * } * }, * { * "feature_id": "1a901a90-1a90-1a90-1a90-1a901a901a95", * "charge_model": "percentage", * "invoiceable": false, * "invoice_display_name": "Setup", * "pay_in_advance": true, * "regroup_paid_fees": "invoice", * "prorated": false, * "min_amount_cents": 0, * "properties": { * "rate": "1", * "fixed_amount": "0.5", * "free_units_per_events": 5, * "free_units_per_total_aggregation": "500" * } * } * ] */ charges?: { /** * Format: uuid * @description Unique identifier of the charge created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id?: string; /** * Format: uuid * @description Unique identifier of the feature created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ feature_id?: string; /** * @description Unique code identifying the charge within the plan. * @example api_requests_charge */ code?: string; charge_model?: components["schemas"]["ChargeModelEnum"]; /** * @description This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. * @example false */ pay_in_advance?: boolean; /** * @description This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`. * @example true */ invoiceable?: boolean; /** * @description This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`. * This field determines whether and when the charge fee should be included in * the invoice. If `null`, no invoice will be issued for this charge fee. * If `invoice`, an invoice will be generated at the end of the period, * consolidating all charge fees with a succeeded payment status. * @example invoice * @enum {string|null} */ regroup_paid_fees?: null | "invoice"; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string; /** * @description Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - If not defined in the request, default value is `false`. * @example false */ prorated?: boolean; /** * @description The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period. * @example 0 */ min_amount_cents?: number; /** @description List of all thresholds utilized for calculating the charge. */ properties?: components["schemas"]["ChargeObjectProperties"]; /** @description List of filters used to apply differentiated pricing based on additional event properties. */ filters?: components["schemas"]["ChargeFilterInput"][]; tax_codes?: components["schemas"]["TaxCodes"]; /** @description Updates the pricing unit conversion rate for this charge. Only applies if the charge has applied pricing unit. */ applied_pricing_unit?: { /** * @description The conversion rate from pricing units to the plan's currency. * This rate determines how many currency units (in the plan's base currency) equal one pricing unit. * For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50 USD. * @example 0.5 */ conversion_rate?: string; }; /** * @description Specifies whether the charge accepts a target wallet for prepaid credits deduction. * @example false */ accepts_target_wallet?: boolean | null; }[]; /** * @description Additional fixed charges for this plan. * @example [ * { * "id": "1a901a90-1a90-1a90-1a90-1a901a901a90", * "invoice_display_name": "New Setup Fee", * "charge_model": "standard", * "apply_units_immediately": true, * "units": 5 * }, * { * "add_on_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", * "code": "setup_fee", * "invoice_display_name": "Setup Fee", * "charge_model": "standard", * "pay_in_advance": true, * "prorated": false, * "properties": { * "amount": "500" * }, * "units": 1, * "apply_units_immediately": false, * "tax_codes": [ * "french_standard_vat" * ] * }, * { * "add_on_id": "4d604d60-4d60-4d60-4d60-4d604d604d60", * "invoice_display_name": "Support Tier", * "charge_model": "graduated", * "pay_in_advance": false, * "prorated": true, * "properties": { * "graduated_ranges": [ * { * "from_value": 0, * "to_value": 10, * "per_unit_amount": "5", * "flat_amount": "200" * }, * { * "from_value": 11, * "to_value": null, * "per_unit_amount": "1", * "flat_amount": "300" * } * ] * }, * "units": 2 * }, * { * "add_on_id": "6f406f40-6f40-6f40-6f40-6f406f406f40", * "charge_model": "volume", * "properties": { * "volume_ranges": [ * { * "from_value": 0, * "to_value": 100, * "per_unit_amount": "2", * "flat_amount": "1" * }, * { * "from_value": 101, * "to_value": null, * "per_unit_amount": "1", * "flat_amount": "0" * } * ] * }, * "units": 50 * } * ] */ fixed_charges?: { /** * Format: uuid * @description Unique identifier of the fixed charge created by Nozle (required for updates). * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id?: string; /** * Format: uuid * @description Unique identifier of the add-on associated with this fixed charge. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ add_on_id?: string; /** * @description Unique code for the fixed charge. If not provided, it will be automatically generated based on the add-on code. * @example setup_fee */ code?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup fee */ invoice_display_name?: string; /** * @description The number of units for the fixed charge. Defaults to 0 if not provided. * @default 0 * @example 1 */ units: number; /** * @description The charge model for the fixed charge. Only `standard`, `graduated`, and `volume` models are supported for fixed charges. * @example standard * @enum {string} */ charge_model?: "standard" | "graduated" | "volume"; /** * @description This field determines the billing timing for this specific fixed charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. Defaults to `false` if not provided. * @default false * @example false */ pay_in_advance: boolean; /** * @description Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - Defaults to `false` if not provided. * * Note: Prorated fixed charges with `graduated` model and `pay_in_advance` are not allowed. * @default false * @example false */ prorated: boolean; /** @description List of all thresholds utilized for calculating the fixed charge. */ properties?: components["schemas"]["FixedChargeProperties"]; /** @description List of taxes applied to the fixed charge. */ tax_codes?: components["schemas"]["TaxCodes"]; /** * @description Determines if the units should be applied immediately upon assignment or deferred to the next billing cycle. * @example true */ apply_units_immediately?: boolean; }[]; /** @description List of usage thresholds to apply to the plan. */ usage_thresholds?: components["schemas"]["UsageThresholdInput"][]; /** * @description Core 11.10.0. Amounts for the other currencies of the plan's family, used when this edit changes the structure of a family sold in several currencies. A structural edit is copied to the family's other plans of the same interval, and money is never copied between currencies: each new or rescaled amount of another currency must come from here, or the whole edit is refused with `plan_family_variant_prices_missing` (its `field` paths are the paths used here). * * Keyed by uppercase currency code. Inside a currency: `amount_cents`; `charges`, keyed by feature code (a second charge of one feature is `#2`), each with `min_amount_cents`, `pricing_unit_conversion_rate`, `properties` (ranges given with their `from_value` and `to_value`) and `filters` keyed by filter key such as `region=eu`; `fixed_charges` keyed by add-on code, each with `properties`; `minimum_commitment` with `amount_cents`; `usage_thresholds` with `amount_cents`, in this plan's order. * * A currency that is not another plan of this plan's interval, or a path this plan does not have, returns `422` with `currency_amounts: [value_is_invalid]` and `currency_amounts_invalid` (`currency`, `field`). Not needed on plan create. The part-edit endpoints (charges, filters, fixed charges) do not take it. See [Multi-currency pricing](/guides/billing/multi-currency-pricing#edit-prices-in-several-currencies). * @example { * "INR": { * "amount_cents": 80000, * "charges": { * "api_calls": { * "min_amount_cents": 0, * "properties": { * "graduated_ranges": [ * { * "from_value": 11, * "to_value": 100, * "per_unit_amount": "83", * "flat_amount": "0" * } * ] * }, * "filters": { * "region=eu": { * "amount": "90" * } * } * } * }, * "fixed_charges": { * "seats": { * "properties": { * "amount": "800" * } * } * }, * "minimum_commitment": { * "amount_cents": 400000 * }, * "usage_thresholds": [ * { * "amount_cents": 800000 * } * ] * } * } */ currency_amounts?: { [key: string]: { [key: string]: unknown; }; }; /** * @description This field determines whether the changes made to the plan should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; /** * @description Plan versioning. A change to what a plan bills or grants (prices, charges, fixed charges, credit grants, entitlements, trial and so on) while subscriptions are on it saves the plan's next version, and those subscriptions keep the version they are on. `true` changes this version in place instead, for every subscription on it from its next invoice. Cannot be combined with `force_version`. See [Plan versioning](/guides/billing/plan-versions). * @example false */ disable_version?: boolean; /** * @description Plan versioning. Saves the change as the plan's next version even when it changes nothing the plan bills or grants. Cannot be combined with `disable_version` (`422`, `force_version: incompatible_with_disable_version`). * @example false */ force_version?: boolean; metadata?: components["schemas"]["MetadataInput"]; }; }; PlanEntitlements: { entitlements: components["schemas"]["PlanEntitlementObject"][]; }; EntitlementUpdateInput: { /** * @description Feature entitlements with their privilege values. Each key is a feature code, and the value is an object containing privilege codes with their associated values. * @example { * "seats": { * "max": 20, * "max_admins": 10, * "root": false * }, * "sso": { * "provider": "microsoft" * } * } */ entitlements: { [key: string]: { [key: string]: number | boolean | string; }; }; }; PlanMetadataResponse: { metadata: components["schemas"]["MetadataObject"]; }; ChargesPaginated: { charges: components["schemas"]["ChargeObject"][]; meta: components["schemas"]["PaginationMeta"]; }; /** @description Properties of a charge that can be overridden at the subscription level. */ ChargeOverridableInput: { /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string; /** * @description The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period. * @example 0 */ min_amount_cents?: number; /** @description List of all thresholds utilized for calculating the charge. */ properties?: components["schemas"]["ChargeObjectProperties"]; /** @description List of filters used to apply differentiated pricing based on additional event properties. */ filters?: components["schemas"]["ChargeFilterInput"][]; tax_codes?: components["schemas"]["TaxCodes"]; /** @description The pricing unit to apply to the charge. */ applied_pricing_unit?: { /** * @description The code of the pricing unit. * @example credits */ code?: string; /** * @description The conversion rate from pricing units to the plan's currency. * This rate determines how many currency units (in the plan's base currency) equal one pricing unit. * For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50. * @example 0.5 */ conversion_rate?: string; }; }; ChargeInput: components["schemas"]["ChargeOverridableInput"] & { /** * Format: uuid * @description Unique identifier of the feature created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ feature_id?: string; /** * @description Unique code identifying the charge within the plan. * @example api_requests_charge */ code?: string; charge_model?: components["schemas"]["ChargeModelEnum"]; /** * @description This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. * @example false */ pay_in_advance?: boolean; /** * @description This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`. * @example true */ invoiceable?: boolean; /** * @description This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`. * This field determines whether and when the charge fee should be included in * the invoice. If `null`, no invoice will be issued for this charge fee. * If `invoice`, an invoice will be generated at the end of the period, * consolidating all charge fees with a succeeded payment status. * @example null * @enum {string|null} */ regroup_paid_fees?: null | "invoice"; /** * @description Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * - If not defined in the request, default value is `false`. * @example false */ prorated?: boolean; }; ChargeCreateInput: { charge: components["schemas"]["ChargeInput"] & unknown & { /** * @description This field determines whether the creation of the charge should be cascaded to the children plans. When set to `true`, the charge will be created in children plans. Conversely, when set to `false`, the charge will only be created in the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; }; }; Charge: { charge: components["schemas"]["ChargeObject"]; }; ChargeUpdateInput: { charge: components["schemas"]["ChargeInput"] & { /** * @description This field determines whether the changes made to the charge should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; }; }; ChargeDeleteInput: { charge?: { /** * @description When set to `true`, the deletion will be cascaded to the children plans. * @example true */ cascade_updates?: boolean; }; }; /** @description Charge filter values used to apply differentiated pricing based on additional event properties. */ ChargeFilterFullObject: { /** * Format: uuid * @description Unique identifier of the charge filter, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Unique code identifying the charge this filter belongs to. * @example api_requests_charge */ charge_code: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name. * @example AWS */ invoice_display_name: string | null; /** @description List of all thresholds utilized for calculating the charge. */ properties: components["schemas"]["ChargeProperties"]; /** * @description List of possible filter values. The key and values must match one of the feature filters. * @example { * "region": [ * "us-east-1" * ] * } */ values: { [key: string]: string[]; }; }; ChargeFiltersPaginated: { filters: components["schemas"]["ChargeFilterFullObject"][]; meta: components["schemas"]["PaginationMeta"]; }; ChargeFilterCreateInput: { filter: { /** * @description This field determines whether the creation of the filter should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name. * @example AWS */ invoice_display_name?: string | null; /** @description List of all thresholds utilized for calculating the charge. */ properties: components["schemas"]["ChargeProperties"]; /** * @description List of possible filter values. The key and values must match one of the feature filters. * @example { * "region": [ * "us-east-1" * ] * } */ values: { [key: string]: string[]; }; }; }; ChargeFilterResponse: { filter: components["schemas"]["ChargeFilterFullObject"]; }; ChargeFilterUpdateInput: { filter: { /** * @description This field determines whether the changes made to the filter should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name. * @example AWS */ invoice_display_name?: string | null; /** @description List of all thresholds utilized for calculating the charge. */ properties?: components["schemas"]["ChargeProperties"]; /** * @description List of possible filter values. The key and values must match one of the feature filters. * @example { * "region": [ * "us-east-1" * ] * } */ values?: { [key: string]: string[]; }; }; }; ChargeFilterDeleteInput: { filter?: { /** * @description When set to `true`, the deletion will be cascaded to the children plans. * @example true */ cascade_updates?: boolean; }; }; FixedChargesPaginated: { fixed_charges: components["schemas"]["FixedChargeObject"][]; meta: components["schemas"]["PaginationMeta"]; }; /** @description Properties of a fixed charge that can be overridden at the subscription level. */ FixedChargeOverridableInput: { /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the add-on will be used as the default display name. * @example Setup Fee */ invoice_display_name?: string | null; /** * @description The quantity of units for the fixed charge. * @example 1.0 */ units?: string; /** * @description When set to `true`, the fixed charge units are applied immediately for active subscriptions. When set to `false`, the units are applied at the next billing period. * @example false */ apply_units_immediately?: boolean; /** @description List of all thresholds utilized for calculating the fixed charge. */ properties?: components["schemas"]["ChargeProperties"]; tax_codes?: components["schemas"]["TaxCodes"]; }; /** * @description Specifies the pricing model used for the calculation of the fixed charge fee. It can be any of the following values: * - `standard` * - `graduated` * - `volume` * @enum {string} */ FixedChargeModelEnum: "standard" | "graduated" | "volume"; FixedChargeInput: components["schemas"]["FixedChargeOverridableInput"] & { /** * Format: uuid * @description Unique identifier of the add-on. Either add_on_id or add_on_code is required. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ add_on_id?: string; /** * @description Unique code identifying an add-on. Either add_on_id or add_on_code is required. * @example setup_fee */ add_on_code?: string; /** * @description Unique code identifying the fixed charge within the plan. * @example setup_fee_charge */ code?: string; charge_model?: components["schemas"]["FixedChargeModelEnum"]; /** * @description This field determines the billing timing for this fixed charge. When set to `true`, the charge is due and invoiced immediately at the beginning of the billing period. When set to `false`, the charge is due and invoiced at the end of the billing period. * @example true */ pay_in_advance?: boolean; /** * @description Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully. * * - If set to `true`, the charge is prorated based on the remaining days in the current billing period. * - If set to `false`, the charge is billed in full. * @example false */ prorated?: boolean; }; FixedChargeCreateInput: { fixed_charge: components["schemas"]["FixedChargeInput"] & { /** * @description This field determines whether the creation of the fixed charge should be cascaded to the children plans. When set to `true`, the fixed charge will be created in children plans. Conversely, when set to `false`, the fixed charge will only be created in the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; }; }; FixedCharge: { fixed_charge: components["schemas"]["FixedChargeObject"]; }; FixedChargeUpdateInput: { fixed_charge: components["schemas"]["FixedChargeInput"] & { /** * @description This field determines whether the changes made to the fixed charge should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`. * @example true */ cascade_updates?: boolean; }; }; FixedChargeDeleteInput: { fixed_charge?: { /** * @description When set to `true`, the deletion will be cascaded to the children plans. * @example true */ cascade_updates?: boolean; }; }; /** @description Based plan overrides. */ PlanOverridesObject: { /** * @description The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan. * @example 10000 */ amount_cents?: number; /** * @description The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. * @example USD */ amount_currency?: components["schemas"]["Currency"]; /** * @description The description on the plan. * @example Plan for early stage startups. */ description?: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name. * @example Startup plan */ invoice_display_name?: string; /** * @description The name of the plan. * @example Startup */ name?: string; tax_codes?: components["schemas"]["TaxCodes"]; /** * @description The duration in days during which the base cost of the plan is offered for free. * @example 5 */ trial_period?: number; minimum_commitment?: components["schemas"]["MinimumCommitmentInput"]; /** @description Additional usage-based charges for this plan. */ charges?: { /** * Format: uuid * @description Unique identifier of the charge created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id?: string; /** * Format: uuid * @description Unique identifier of the feature created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ feature_id?: string; /** * @description Unique code identifying the charge within the plan. * @example api_requests_charge */ code?: string; charge_model?: components["schemas"]["ChargeModelEnum"]; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup */ invoice_display_name?: string; /** * @description The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period. * @example 0 */ min_amount_cents?: number; /** @description List of all thresholds utilized for calculating the charge. */ properties?: components["schemas"]["ChargeObjectProperties"]; /** @description List of filters used to apply differentiated pricing based on additional event properties. */ filters?: components["schemas"]["ChargeFilterInput"][]; tax_codes?: components["schemas"]["TaxCodes"]; /** @description Updates the pricing unit conversion rate for this charge. Only applies if the charge has applied pricing unit. */ applied_pricing_unit?: { /** * @description The conversion rate from pricing units to the plan's currency. * This rate determines how many currency units (in the plan's base currency) equal one pricing unit. * For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50 USD. * @example 0.5 */ conversion_rate?: string; }; }[]; /** @description Fixed charge overrides for the subscription. When `plan_overrides` contains only `fixed_charges` and every entry contains only `id`, `units`, and optionally `apply_units_immediately`, the units are recorded as a per-subscription override without creating a plan override, and subscription-scoped reads return these units. If any entry carries other fields, or `plan_overrides` contains any other key, the request is applied as a full plan override for the subscription instead. */ fixed_charges?: { /** * Format: uuid * @description Unique identifier of the fixed charge created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ id: string; /** * @description Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. * @example Setup fee */ invoice_display_name?: string; /** * @description The number of units for the fixed charge. Defaults to 0 if not provided. * @default 0 * @example 1 */ units: number; /** * @description Determines if the units should be applied immediately upon assignment or deferred to the next billing cycle. * @example true */ apply_units_immediately?: boolean; /** @description List of all thresholds utilized for calculating the fixed charge. */ properties?: components["schemas"]["FixedChargeProperties"]; /** @description List of taxes applied to the fixed charge. */ tax_codes?: components["schemas"]["TaxCodes"]; }[]; /** @description List of usage thresholds applied to the subscription. */ usage_thresholds?: components["schemas"]["UsageThresholdInput"][]; metadata?: components["schemas"]["MetadataInput"]; }; SubscriptionActivationRuleInput: { /** * @description The type of the activation rule. Only `payment` is currently supported. A `payment` rule gates the subscription activation on a successful payment of the first invoice. * @example payment * @enum {string} */ type: "payment"; /** * @description The number of hours the subscription stays in the `incomplete` state waiting for the payment to succeed before it is automatically canceled. Must be a positive integer or zero. * @example 48 */ timeout_hours?: number; }; SubscriptionCreateInput: { /** * @description Optionally, you can create a pre-authorization on the customer's card before creating a subscription. This process places a temporary hold (capture) for a specified amount on the customer's account, but does not actually withdraw the funds. * * Important notes: * - The final amount due for the subscription is not known at the time of creation; it is determined only after the invoice is finalized. * - The payment intent generated for pre-authorization cannot be reused, as the final invoice amount may exceed the authorized amount. * - The payment intent is canceled immediately after creation, but this cancellation occurs asynchronously. * - For these reasons, it is recommended to use a small amount (such as $1) for pre-authorization. While this does not guarantee sufficient funds for the final payment, it helps reduce the likelihood of payment errors. */ authorization?: { /** * @description The amount of the authorization in cents. * @example 1000 */ amount_cents: number; /** * @description The currency of the authorization. * @example USD */ amount_currency: string; }; /** @description Send `plan_code`, or `plan_family_code` with `interval` (and optional `currency`). */ subscription: { /** * @description The code of the billing entity to be used for the subscription. If not provided, the default billing entity will be used. * @example default */ billing_entity_code?: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The unique code representing the plan to be attached to the customer. This code must correspond to the `code` property of one of the active plans. Required unless `plan_family_code` is sent. * @example premium */ plan_code?: string; /** * @description Core 11.10.0. Sells a plan family instead of `plan_code`; Nozle picks the family's current plan for `interval` and `currency`. Cannot be combined with `plan_code` (`422`, `plan_family_code: [incompatible_with_plan_code]`). An unknown family returns `404 plan_family_not_found`. See [Multi-currency pricing](/guides/billing/multi-currency-pricing#checkout-and-subscribe-by-family). * @example pro */ plan_family_code?: string; /** * @description Required with `plan_family_code` (`interval: [value_is_mandatory]` without it, `[value_is_invalid]` for an unknown value). * @example yearly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description With `plan_family_code`, the ISO 4217 code of the plan to sell. Without it, the currency of the subscription being changed, else the customer's locked currency, else the family's default currency. A currency the family does not sell for that interval returns `422` with `currency: [currency_not_offered]`. * @example EUR */ currency?: string; /** * @description Optional. The version of `plan_code` to sell, for example to keep selling an older price to a customer. Without it, a new subscription gets the current version. * * Sending the `external_id` of an existing subscription with its own `plan_code` changes nothing and returns it, whatever the current version is. A `plan_version` other than the subscription's own is refused with `422` (`plan_version: plan_version_change_not_supported`): only a version migration moves a subscription between versions. An unknown version returns `404` with `plan_version_not_found`. * @example 1 */ plan_version?: number; /** * @description The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan. * @example Repository A */ name?: string; /** * @description The unique external identifier for the subscription. This identifier serves as an idempotency key, ensuring that each subscription is unique. * @example my_sub_1234567890 */ external_id: string; /** * @description The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration). * @example anniversary * @enum {string} */ billing_time?: "calendar" | "anniversary"; /** * Format: date-time * @description The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC). * @example 2022-10-08T00:00:00Z */ ending_at?: string; /** * Format: date-time * @description The start date for the subscription, allowing for the creation of subscriptions that can begin in the past or future. Please note that it cannot be used to update the start date of a pending subscription or schedule an upgrade/downgrade. The start_date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ subscription_at?: string; /** @description Overrides applied to the plan for this subscription. A units-only `fixed_charges` override is recorded as a per-subscription unit override without creating a plan override; any other override creates a plan override for the subscription. See `fixed_charges` for the exact rule. */ plan_overrides?: components["schemas"]["PlanOverridesObject"]; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description Optional payment method to use for processing subscription payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; /** * @description Defines whether this subscription should be grouped with other subscriptions of the same customer when generating recurring invoices. * * - `true` (default): the subscription is included in the customer's standard invoice grouping (by billing entity, currency and payment method). * - `false`: the subscription is excluded from consolidation and always billed on its own dedicated invoice. * @default true * @example true */ consolidate_invoice: boolean; /** @description Optional list of activation rules that gate the subscription activation. When a `payment` rule is provided and the plan is paid in advance (and the subscription is not in a trial), the subscription is created in the `incomplete` state and is only activated once the gating payment succeeds. If the payment fails or the rule's `timeout_hours` elapses, the subscription is canceled. */ activation_rules?: components["schemas"]["SubscriptionActivationRuleInput"][]; }; }; ApplicableUsageThreshold: { /** * @description The display name of the usage threshold. * @example Threshold 1 */ threshold_display_name: string | null; /** * @description The amount to reach to trigger a `progressive_billing` invoice. * @example 10000 */ amount_cents: number; /** * @description This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount. * @example true */ recurring: boolean; }; SubscriptionObjectExtended: components["schemas"]["SubscriptionObject"] & { plan?: components["schemas"]["PlanObject"]; /** @description List of usage thresholds applicable to this subscription. */ applicable_usage_thresholds?: components["schemas"]["ApplicableUsageThreshold"][]; }; SubscriptionExtended: { subscription: components["schemas"]["SubscriptionObjectExtended"]; }; SubscriptionUpdateInput: { /** * @description If the field is not defined and multiple `active` and `pending` subscriptions exists, Nozle will update the `active` subscription. However, if you wish to update a `pending` subscription, please ensure that you include the `status` attribute with the `pending` value in your request body. * @example active * @enum {string} */ status?: "active" | "pending"; subscription: { /** * @description The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan. * @example Repository B */ name?: string | null; /** * Format: date-time * @description The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC). * @example 2022-10-08T00:00:00Z */ ending_at: string | null; /** * Format: date-time * @description The start date and time of the subscription. This field can only be modified for pending subscriptions that have not yet started. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-08-08T00:00:00Z */ subscription_at?: string; /** @description Overrides applied to the plan for this subscription. A units-only `fixed_charges` override is recorded as a per-subscription unit override without creating a plan override; any other override creates a plan override for the subscription. See `fixed_charges` for the exact rule. */ plan_overrides?: components["schemas"]["PlanOverridesObject"]; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description Optional payment method to use for processing subscription payments. */ payment_method?: components["schemas"]["PaymentMethodReference"]; /** * @description Defines whether this subscription should be grouped with other subscriptions of the same customer when generating recurring invoices. * * - `true`: the subscription is included in the customer's standard invoice grouping (by billing entity, currency and payment method). * - `false`: the subscription is excluded from consolidation and always billed on its own dedicated invoice. * @example false */ consolidate_invoice?: boolean; /** * @description The code of the billing entity associated with the subscription. Updates take effect on future invoices only. * @example default */ billing_entity_code?: string; /** @description Optional list of activation rules that gate the subscription activation. Activation rules can only be set or modified while the subscription is `pending` (future-dated and not yet activated); the request is rejected for `incomplete`, `active`, or `terminated` subscriptions. */ activation_rules?: components["schemas"]["SubscriptionActivationRuleInput"][]; }; }; Subscription: { subscription: components["schemas"]["SubscriptionObject"]; }; LifetimeUsageThresholdObject: { /** * @description The usage threshold amount in cents. * @example 100 */ amount_cents: number; /** * @description The completion ratio of the usage threshold. * @example 0.5 */ completion_ratio: number; /** * Format: date-time * @description The date and time when the usage threshold was reached. The date and time must be in ISO 8601 format. * @example 2024-01-01T00:00:00Z */ reached_at: string | null; }; LifetimeUsageObject: { /** * Format: uuid * @description Unique identifier assigned to the lifetime usage record within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the lifetime usage record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier assigned to the subscription record within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the subscription record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id: string; /** * @description The subscription external unique identifier (provided by your own application). * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_subscription_id: string; /** * @description The historical usage amount in cents for the subscription (provided by your own application). * @example 100 */ external_historical_usage_amount_cents: number; /** * @description The total invoiced usage amount in cents for the subscription. * @example 100 */ invoiced_usage_amount_cents: number; /** * @description The current usage amount in cents for the subscription on the current billing period. * @example 100 */ current_usage_amount_cents: number; /** * Format: date-time * @description The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format. * @example 2024-01-01T00:00:00Z */ from_datetime: string | null; /** * Format: date-time * @description The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format. * @example 2024-12-31T23:59:59Z */ to_datetime: string; /** @description Array of usage thresholds attached to the subscription's plan. */ usage_thresholds?: components["schemas"]["LifetimeUsageThresholdObject"][]; }; LifetimeUsage: { lifetime_usage: components["schemas"]["LifetimeUsageObject"]; }; LifetimeUsageInput: { lifetime_usage: { /** * @description The historical usage amount in cents for the subscription (provided by your own application). * @example 100 */ external_historical_usage_amount_cents: number; }; }; AlertObject: { /** * Format: uuid * @description Unique identifier of the alert, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the organization, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * @description The subscription external unique identifier (provided by your own application). * @example sub_1234567890 */ external_subscription_id: string | null; wallet_id?: null; wallet_code?: null; /** @description The feature associated with the alert. Only for alerts based on a feature. */ feature: components["schemas"]["FeatureObject"]; /** * @description The type of alert. * @example feature_current_usage_amount * @enum {string} */ alert_type: "current_usage_amount" | "feature_current_usage_amount" | "feature_current_usage_units" | "lifetime_usage_amount"; /** * @description Unique code used to identify the alert. * @example storage_threshold_alert */ code: string; /** * @description The name of the alert. * @example Storage Usage Alert */ name: string | null; /** * @description Indicates whether the alert is triggered when the monitored metric goes above or below the threshold. * @example increasing * @enum {string} */ direction?: "increasing" | "decreasing"; /** * @description When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds. * @example 1000 */ previous_value: number; /** * Format: date-time * @description The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time. * @example 2025-05-19T10:04:21Z */ last_processed_at: string | null; /** @description Array of thresholds associated with the alert. */ thresholds: components["schemas"]["AlertThresholdObject"][]; /** * Format: date-time * @description The date and time in UTC (ISO 8601) when the alert was created. * @example 2025-03-20T10:00:00Z */ created_at: string; }; Alerts: { alerts: components["schemas"]["AlertObject"][]; meta?: components["schemas"]["PaginationMeta"]; }; AlertCreateInput: { alert: components["schemas"]["AlertBaseInput"] & { /** * @description The type of alert. * @example feature_current_usage_amount * @enum {string} */ alert_type: "current_usage_amount" | "feature_current_usage_amount" | "feature_current_usage_units" | "lifetime_usage_amount"; /** * @description Unique code used to identify the alert. * @example storage_threshold_alert */ code: string; /** * @description The code of the feature associated with the alert. Only for alerts based on a feature. * @example storage_usage */ feature_code?: string | null; }; }; AlertBatchCreateInput: { /** @description Array of alerts to create. All alerts are created atomically - if any fail validation, none are created. */ alerts: (components["schemas"]["AlertBaseInput"] & { /** * @description The type of alert. * @example feature_current_usage_amount * @enum {string} */ alert_type: "current_usage_amount" | "feature_current_usage_amount" | "feature_current_usage_units" | "lifetime_usage_amount"; /** * @description Unique code used to identify the alert. * @example storage_threshold_alert */ code: string; /** * @description The code of the feature associated with the alert. Only for alerts based on a feature. * @example storage_usage */ feature_code?: string | null; })[]; }; Alert: { alert: components["schemas"]["AlertObject"]; }; AlertUpdateInput: { alert: components["schemas"]["AlertBaseInput"] & { /** * @description The code of the feature associated with the alert. Only for alerts based on a feature. * @example storage_usage */ feature_code?: string | null; }; }; SubscriptionEntitlementPrivilegeObject: components["schemas"]["FeaturePrivilegeObject"] & { /** * @description Applicable value this this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type. * @example 10 */ value: number | boolean | string; /** * @description Value assigned to this privilege in the plan. Type depends on the privilege's value_type. * @example 10 */ plan_value: number | boolean | string; /** * @description Value assigned to this subscription specifically. Type depends on the privilege's value_type. Null if no override is set. * @example 10 */ override_value: number | boolean | string | null; }; SubscriptionEntitlementObject: { /** * @description Unique code used to identify the feature. Max 255 characters. * @example seats */ code: string; /** * @description Name of the feature. Max 255 characters. * @example Number of seats */ name: string | null; /** * @description Description of the feature. Max 600 characters. * @example Number of users of the account */ description: string | null; /** * @description Privileges associated with this feature. Each privilege shows the plan value and any subscription override. * @example [ * { * "code": "max", * "name": "Maximum", * "value_type": "integer", * "config": {}, * "value": 15, * "plan_value": 10, * "override_value": 15 * }, * { * "code": "max_admins", * "name": "Max Admins", * "value_type": "integer", * "config": {}, * "value": 5, * "plan_value": 5, * "override_value": null * }, * { * "code": "root", * "name": "Allow root user", * "value_type": "boolean", * "config": {}, * "value": true, * "plan_value": true, * "override_value": null * }, * { * "code": "provider", * "name": "SSO Provider", * "value_type": "select", * "value": "microsoft", * "plan_value": "google", * "override_value": "microsoft", * "config": { * "select_options": [ * "google", * "microsoft" * ] * } * } * ] */ privileges: components["schemas"]["SubscriptionEntitlementPrivilegeObject"][]; /** * @example { * "max": 15, * "provider": "microsoft" * } */ overrides: { [key: string]: unknown; }; }; SubscriptionEntitlements: { entitlements: components["schemas"]["SubscriptionEntitlementObject"][]; }; SubscriptionEntitlement: { entitlement: components["schemas"]["SubscriptionEntitlementObject"]; }; SubscriptionChargeOverride: { charge: components["schemas"]["ChargeOverridableInput"]; }; SubscriptionFixedChargeOverride: { fixed_charge: components["schemas"]["FixedChargeOverridableInput"]; }; TaxesPaginated: { taxes: components["schemas"]["TaxObject"][]; meta: components["schemas"]["PaginationMeta"]; }; TaxBaseInput: { /** * @description Name of the tax. * @example TVA */ name?: string; /** * @description Unique code used to identify the tax associated with the API request. * @example french_standard_vat */ code?: string; /** * @description The percentage rate of the tax * @example 20.0 */ rate?: string; /** * @description Internal description of the taxe * @example French standard VAT */ description?: string | null; /** * @deprecated * @description This field is deprecated and will be removed in a future version. When set to true, it applies the tax to the organization's default billing entity. To apply or remove a tax from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead. * @example true */ applied_to_organization?: boolean; }; TaxCreateInput: { tax: components["schemas"]["TaxBaseInput"]; }; Tax: { tax: components["schemas"]["TaxObject"]; }; TaxUpdateInput: { tax: components["schemas"]["TaxBaseInput"]; }; WalletTransactionCreateInput: { wallet_transaction: { /** * Format: uuid * @description Unique identifier assigned to the wallet within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the wallet's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ wallet_id: string; /** * @description The name of the wallet transaction. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. * * Note that this name will apply to all transactions (`paid_credits`, `granted_credits` and `voided_credits`) created by this action. * @example Tokens for models 'high-fidelity-boost' */ name?: string | null; /** * @description The number of paid credits. * @example 20.0 */ paid_credits?: string | null; /** * @description The number of free granted credits. * @example 10.0 */ granted_credits?: string | null; /** * @description The number of voided credits. * @example 5.0 */ voided_credits?: string | null; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment?: boolean; /** * @description When true, allows topping up the wallet with transactions that exceed the paid top-up limits. Defaults to false. * @example false */ ignore_paid_top_up_limits?: boolean; invoice_custom_section?: components["schemas"]["InvoiceCustomSectionInput"]; /** @description Optional payment method to use for processing the wallet transaction payment. */ payment_method?: components["schemas"]["PaymentMethodReference"]; /** * @description This optional field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data. * @example [ * { * "key": "example key", * "value": "example value" * }, * { * "key": "another key", * "value": "another value" * } * ] */ metadata?: { /** @description The unique identifier for the attribute. */ key?: string; /** @description The value associated with the key. */ value?: string; }[] | null; }; }; WalletTransactionObject: { /** * Format: uuid * @description Unique identifier assigned to the wallet transaction within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the wallet transaction's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier assigned to the wallet within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the wallet's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ wallet_id: string; /** * Format: uuid * @description Unique identifier assigned to the invoice associated with this wallet transaction. This ID is exclusively created by Nozle and serves as a unique identifier for the invoice's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string | null; /** * Format: uuid * @description Unique identifier of the credit note associated with this wallet transaction. This ID is exclusively created by Nozle and serves as a unique identifier for the invoice's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ credit_note_id: string | null; /** * Format: uuid * @description Unique identifier of the invoice that was voided and triggered the creation of this inbound wallet transaction. Only present for inbound transactions on traceable wallets that were created as a result of an invoice void. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ voided_invoice_id: string | null; /** * @description The status of the wallet transaction. Possible values are `pending`, `settled` or `failed`. * @example settled * @enum {string} */ status: "pending" | "settled" | "failed"; /** * @description The source field represents the origin or trigger of the wallet transaction. Possible values are `manual`, `interval`, `threshold` * @example manual * @enum {string} */ source: "manual" | "interval" | "threshold"; /** * @description The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`. * @example purchased * @enum {string} */ transaction_status: "purchased" | "granted" | "voided" | "invoiced"; /** * @description The type of transaction. Possible values are `inbound` (increasing the balance) or `outbound` (decreasing the balance). * @example inbound * @enum {string} */ transaction_type: "inbound" | "outbound"; /** * @description The amount of credits based on the rate and the currency. * @example 10.0 */ amount: string; /** * @description The number of credits used in the wallet transaction. * @example 100.0 */ credit_amount: string; /** * @description A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false. * @example false */ invoice_requires_successful_payment: boolean; /** * @description This field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data. * @example [ * { * "key": "example key", * "value": "example value" * }, * { * "key": "another key", * "value": "another value" * } * ] */ metadata: { /** @description The unique identifier for the attribute. */ key?: string; /** @description The value associated with the key. */ value?: string; }[]; /** * @description The remaining unconsumed amount of an inbound wallet transaction, expressed in cents. Only present for inbound transactions on traceable wallets. Tracks how much of the original credited amount has not yet been consumed by outbound transactions. * @example 5000 */ remaining_amount_cents: number | null; /** * @description The remaining unconsumed amount of an inbound wallet transaction, expressed in credits. Only present for inbound transactions on traceable wallets. * @example 5.0 */ remaining_credit_amount: string | null; /** * @description The priority of the wallet transaction, used to determine the order in which inbound transactions are consumed. Lower values are consumed first. * @example 50 */ priority: number; /** * Format: date-time * @description The date when wallet transaction is settled, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ settled_at: string | null; /** * Format: date-time * @description The date when the wallet transaction failed, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ failed_at: string | null; /** * Format: date-time * @description The date of the wallet transaction creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ created_at: string; /** * @description The name of the wallet transaction. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. * @example Tokens for models 'high-fidelity-boost' */ name: string | null; /** @description The invoice custom sections applied to invoices generated by this wallet transaction. */ applied_invoice_custom_sections?: components["schemas"]["AppliedInvoiceCustomSectionObject"][]; /** @description The payment method assigned to this wallet transaction for processing the payment. */ payment_method: components["schemas"]["PaymentMethodReference"]; }; WalletTransactions: { wallet_transactions: components["schemas"]["WalletTransactionObject"][]; }; WalletTransactionPaymentUrl: { wallet_transaction_payment_details: { /** * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description Unique identifier assigned to the wallet transaction within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the wallet transaction's record within the Nozle system * @example 1e501a90-1a90-1a90-1a90-1a901a901a80 */ wallet_transaction_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The Payment Provider name linked to the Customer. * @example stripe */ payment_provider: string; /** * @description The generated Payment URL for the Wallet transaction. * @example https://foo.bar */ payment_url: string; }; }; WalletTransactionConsumptionObject: { /** * Format: uuid * @description Unique identifier assigned to the wallet transaction consumption within the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The amount consumed from the inbound wallet transaction, expressed in cents. * @example 5000 */ amount_cents: number; /** * @description The amount consumed from the inbound wallet transaction, expressed in credits. * @example 5.0 */ credit_amount: string; /** * Format: date-time * @description The date of the consumption record creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ created_at: string; wallet_transaction: components["schemas"]["WalletTransactionObject"]; }; WalletTransactionConsumptions: { wallet_transaction_consumptions: components["schemas"]["WalletTransactionConsumptionObject"][]; }; WalletTransactionConsumptionsPaginated: components["schemas"]["WalletTransactionConsumptions"] & { meta: components["schemas"]["PaginationMeta"]; }; WalletTransactionFundingObject: { /** * Format: uuid * @description Unique identifier assigned to the wallet transaction funding within the Nozle application. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description The amount funded from the inbound wallet transaction, expressed in cents. * @example 5000 */ amount_cents: number; /** * @description The amount funded from the inbound wallet transaction, expressed in credits. * @example 5.0 */ credit_amount: string; /** * Format: date-time * @description The date of the funding record creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ created_at: string; wallet_transaction: components["schemas"]["WalletTransactionObject"]; }; WalletTransactionFundings: { wallet_transaction_fundings: components["schemas"]["WalletTransactionFundingObject"][]; }; WalletTransactionFundingsPaginated: components["schemas"]["WalletTransactionFundings"] & { meta: components["schemas"]["PaginationMeta"]; }; WalletTransactionsPaginated: components["schemas"]["WalletTransactions"] & { meta: components["schemas"]["PaginationMeta"]; }; WebhookEndpointObject: { /** * Format: uuid * @description Unique identifier assigned to the wallet within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the webhook endpoint's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier assigned to the organization attached to the webhook endpoint within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the organization's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * @description The URL Nozle sends the webhooks to. * @example https://app.example.com/nozle/webhooks */ webhook_url: string; /** * @description The endpoint secret (`whsec_...`) used to verify `standard` signatures. The REST API returns it to any API key with the `webhook_endpoint` read permission; the dashboard (GraphQL) shows it only to members with `developers:manage`. Keep such API keys on your server. * @example whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw */ secret?: string | null; /** * Format: date-time * @description When the previous secret stops being valid after a rotation (24 hours after `rotate_secret`). `null` when no rotation happened or the grace has passed. */ previous_secret_expires_at?: string | null; /** * Format: date-time * @description Set when Nozle disabled the endpoint after 5 days without a successful delivery. No webhooks are created for it until you re-enable it with `disabled: false`. */ disabled_at?: string | null; /** * Format: date-time * @description The date of the webhook endpoint creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). * @example 2022-04-29T08:59:51Z */ created_at: string; /** * @description A label for the endpoint. * @example Production */ name?: string | null; /** @description Event types the endpoint receives. `null` means every type. */ event_types?: ("alert.triggered" | "customer.created" | "customer.updated" | "customer.accounting_provider_created" | "customer.accounting_provider_error" | "customer.crm_provider_created" | "customer.crm_provider_error" | "customer.payment_provider_created" | "customer.payment_provider_error" | "customer.checkout_url_generated" | "customer.tax_provider_error" | "customer.vies_check" | "credit_note.created" | "credit_note.generated" | "credit_note.refund_failure" | "dunning_campaign.finished" | "dunning.step" | "event.error" | "events.errors" | "feature.created" | "feature.updated" | "feature.deleted" | "fee.created" | "fee.tax_provider_error" | "invoice.created" | "invoice.one_off_created" | "invoice.paid_credit_added" | "invoice.generated" | "invoice.drafted" | "invoice.voided" | "invoice.payment_dispute_lost" | "invoice.payment_dispute_updated" | "invoice.payment_status_updated" | "invoice.payment_overdue" | "invoice.payment_failure" | "invoice.resynced" | "integration.provider_error" | "order.created" | "order.executed" | "order.failed" | "order_form.created" | "order_form.signed" | "order_form.expired" | "order_form.voided" | "payment.succeeded" | "payment.requires_action" | "payment.scheduled" | "payment.schedule_cancelled" | "payment_provider.error" | "payment_receipt.created" | "payment_receipt.generated" | "payment_request.created" | "payment_request.payment_failure" | "payment_request.payment_status_updated" | "plan.created" | "plan.updated" | "plan.version_created" | "plan.deleted" | "plan_upgrade_intent.needs_review" | "quote.created" | "quote.approved" | "quote.voided" | "subscription.canceled" | "subscription.incomplete" | "subscription.terminated" | "subscription.started" | "subscription.updated" | "subscription.termination_alert" | "subscription.trial_ended" | "subscription.usage_threshold_reached" | "credit_top_up_purchase.fulfilled" | "wallet.created" | "wallet.depleted_ongoing_balance" | "wallet.terminated" | "wallet.updated" | "wallet_transaction.created" | "wallet_transaction.updated" | "wallet_transaction.payment_failure")[] | null; }; WebhookObject: { /** * Format: uuid * @description The webhook id. It is the `webhook-id` header of every attempt. */ nozle_id: string; /** Format: uuid */ webhook_endpoint_id: string; /** @example invoice.created */ webhook_type: string; /** @enum {string} */ status: "pending" | "succeeded" | "failed" | "retrying"; /** @description The URL the webhook is sent to. */ endpoint?: string; /** @description HTTP status of the last attempt. */ http_status?: number | null; /** @description Number of retries made so far. */ retries?: number; object_type?: string | null; object_id?: string | null; payload?: { [key: string]: unknown; }; /** @description Body of the last response from your endpoint. */ response?: unknown; /** Format: date-time */ last_retried_at?: string | null; /** Format: date-time */ created_at?: string; /** Format: date-time */ updated_at?: string; }; WebhookResult: { webhook: components["schemas"]["WebhookObject"]; }; WebhooksPaginated: { webhooks: components["schemas"]["WebhookObject"][]; meta: components["schemas"]["PaginationMeta"]; }; WebhookRecoverResult: { recover: { /** Format: uuid */ webhook_endpoint_id?: string; /** @description How many failed webhooks were queued again. */ retried_webhooks?: number; }; }; WebhookEndpointsPaginated: { webhook_endpoints: components["schemas"]["WebhookEndpointObject"][]; meta: components["schemas"]["PaginationMeta"]; }; WebhookEndpointCreateInput: { webhook_endpoint?: { /** * @description The URL of the webhook endpoint. * @example https://foo.bar */ webhook_url: string; /** * @description A label for the endpoint. * @example Production */ name?: string | null; /** * @description Event types the endpoint receives, from the [webhook event list](/api/webhook-events). Send `null` or `["*"]` (or leave it out) to receive every type; an empty array is rejected. The former name `credit_note.provider_refund_failure` is accepted and saved as `credit_note.refund_failure`. An unknown type is rejected with a 422 `invalid_types` error. * @example [ * "subscription.started", * "invoice.payment_status_updated" * ] */ event_types?: ("alert.triggered" | "customer.created" | "customer.updated" | "customer.accounting_provider_created" | "customer.accounting_provider_error" | "customer.crm_provider_created" | "customer.crm_provider_error" | "customer.payment_provider_created" | "customer.payment_provider_error" | "customer.checkout_url_generated" | "customer.tax_provider_error" | "customer.vies_check" | "credit_note.created" | "credit_note.generated" | "credit_note.refund_failure" | "dunning_campaign.finished" | "dunning.step" | "event.error" | "events.errors" | "feature.created" | "feature.updated" | "feature.deleted" | "fee.created" | "fee.tax_provider_error" | "invoice.created" | "invoice.one_off_created" | "invoice.paid_credit_added" | "invoice.generated" | "invoice.drafted" | "invoice.voided" | "invoice.payment_dispute_lost" | "invoice.payment_dispute_updated" | "invoice.payment_status_updated" | "invoice.payment_overdue" | "invoice.payment_failure" | "invoice.resynced" | "integration.provider_error" | "order.created" | "order.executed" | "order.failed" | "order_form.created" | "order_form.signed" | "order_form.expired" | "order_form.voided" | "payment.succeeded" | "payment.requires_action" | "payment.scheduled" | "payment.schedule_cancelled" | "payment_provider.error" | "payment_receipt.created" | "payment_receipt.generated" | "payment_request.created" | "payment_request.payment_failure" | "payment_request.payment_status_updated" | "plan.created" | "plan.updated" | "plan.version_created" | "plan.deleted" | "plan_upgrade_intent.needs_review" | "quote.created" | "quote.approved" | "quote.voided" | "subscription.canceled" | "subscription.incomplete" | "subscription.terminated" | "subscription.started" | "subscription.updated" | "subscription.termination_alert" | "subscription.trial_ended" | "subscription.usage_threshold_reached" | "credit_top_up_purchase.fulfilled" | "wallet.created" | "wallet.depleted_ongoing_balance" | "wallet.terminated" | "wallet.updated" | "wallet_transaction.created" | "wallet_transaction.updated" | "wallet_transaction.payment_failure")[] | null; }; }; WebhookEndpoint: { webhook_endpoint: components["schemas"]["WebhookEndpointObject"]; }; WebhookEndpointUpdateInput: { webhook_endpoint?: { /** * @description Send `true` to disable the endpoint, or `false` to re-enable one Nozle disabled (clears `disabled_at`). * @example false */ disabled?: boolean; /** * @description The URL of the webhook endpoint. * @example https://foo.bar */ webhook_url?: string; /** * @description A label for the endpoint. * @example Production */ name?: string | null; /** * @description Event types the endpoint receives, from the [webhook event list](/api/webhook-events). Send `null` or `["*"]` (or leave it out) to receive every type; an empty array is rejected. The former name `credit_note.provider_refund_failure` is accepted and saved as `credit_note.refund_failure`. An unknown type is rejected with a 422 `invalid_types` error. * @example [ * "subscription.started", * "invoice.payment_status_updated" * ] */ event_types?: ("alert.triggered" | "customer.created" | "customer.updated" | "customer.accounting_provider_created" | "customer.accounting_provider_error" | "customer.crm_provider_created" | "customer.crm_provider_error" | "customer.payment_provider_created" | "customer.payment_provider_error" | "customer.checkout_url_generated" | "customer.tax_provider_error" | "customer.vies_check" | "credit_note.created" | "credit_note.generated" | "credit_note.refund_failure" | "dunning_campaign.finished" | "dunning.step" | "event.error" | "events.errors" | "feature.created" | "feature.updated" | "feature.deleted" | "fee.created" | "fee.tax_provider_error" | "invoice.created" | "invoice.one_off_created" | "invoice.paid_credit_added" | "invoice.generated" | "invoice.drafted" | "invoice.voided" | "invoice.payment_dispute_lost" | "invoice.payment_dispute_updated" | "invoice.payment_status_updated" | "invoice.payment_overdue" | "invoice.payment_failure" | "invoice.resynced" | "integration.provider_error" | "order.created" | "order.executed" | "order.failed" | "order_form.created" | "order_form.signed" | "order_form.expired" | "order_form.voided" | "payment.succeeded" | "payment.requires_action" | "payment.scheduled" | "payment.schedule_cancelled" | "payment_provider.error" | "payment_receipt.created" | "payment_receipt.generated" | "payment_request.created" | "payment_request.payment_failure" | "payment_request.payment_status_updated" | "plan.created" | "plan.updated" | "plan.version_created" | "plan.deleted" | "plan_upgrade_intent.needs_review" | "quote.created" | "quote.approved" | "quote.voided" | "subscription.canceled" | "subscription.incomplete" | "subscription.terminated" | "subscription.started" | "subscription.updated" | "subscription.termination_alert" | "subscription.trial_ended" | "subscription.usage_threshold_reached" | "credit_top_up_purchase.fulfilled" | "wallet.created" | "wallet.depleted_ongoing_balance" | "wallet.terminated" | "wallet.updated" | "wallet_transaction.created" | "wallet_transaction.updated" | "wallet_transaction.payment_failure")[] | null; }; }; TriggeredAlertObject: { /** * Format: uuid * @description Unique identifier of the alert, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the organization, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * Format: uuid * @description Unique identifier of the alert, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ alert_id: string; /** * Format: uuid * @description Unique identifier of the subscription, created by Nozle. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id: string; /** * @description The subscription external unique identifier (provided by your own application). * @example sub_1234567890 */ external_subscription_id: string; /** * @description The customer external unique identifier (provided by your own application). * @example cust_1234567890 */ external_customer_id: string; /** * @description The code of the feature associated with the alert. Only for alerts based on a feature. * @example storage_usage */ feature_code: string | null; /** * @description The type of alert triggered. * @example feature_current_usage_amount * @enum {string} */ alert_type: "current_usage_amount" | "feature_current_usage_amount" | "feature_current_usage_units" | "lifetime_usage_amount"; /** * @description Unique code used to identify the alert triggered. * @example storage_threshold_alert */ alert_code: string; /** * @description The name of the alert triggered. * @example Storage Usage Alert */ alert_name: string | null; /** * @description When the system checked if this alert should be triggered, this value was retrieved and checked if any threshold were crossed between this value and previous value. A decimal, sent as a string. * @example 1200.0 */ current_value: string; /** * @description During the previous run, this value was retrieved. A decimal, sent as a string. * @example 1200.0 */ previous_value: string; /** * Format: date-time * @description The date and time in UTC (ISO 8601) when the system triggered the alert. * @example 2025-05-19T10:04:21Z */ triggered_at: string | null; /** @description Array of thresholds crossed. All the recurring threshold values are present. */ crossed_thresholds: components["schemas"]["AlertThresholdObject"][]; wallet_id?: string | null; subscription_external_id?: string; customer_external_id?: string; }; CustomerIntegratrionErrorObject: { /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The type of accounting provider code * @example anrok * @enum {string} */ accounting_provider: "anrok"; /** * @description Code of the accounting provider * @example Anrok Prod */ accounting_provider_code: string; provider_error: string | { [key: string]: unknown; }; }; CustomerPaymentProviderErrorObject: { /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The type of payment provider * @example stripe * @enum {string} */ payment_provider: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash"; /** * @description Code of the payment provider * @example Stripe Prod */ payment_provider_code: string; provider_error: string | { [key: string]: unknown; }; }; CustomerTaxProviderErrorObject: { /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description The type of tax provider * @example anrock * @enum {string} */ tax_provider: "anrock"; /** * @description Code of the tax provider * @example Stripe Prod */ tax_provider_code: string; provider_error: string | { [key: string]: unknown; }; }; CustomerViesCheckObject: components["schemas"]["CustomerBaseObject"] & { vies_check?: { /** * @description Whether the VIES check was successful * @example true */ valid?: boolean; country_code?: string; vat_number?: string; request_date?: string; name?: string; address?: string; }; external_salesforce_id?: string | null; }; CreditNotePaymentProviderRefundError: { /** * Format: uuid * @description Unique identifier assigned to the credit note within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the credit note record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ credit_note_id: string; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description Unique identifier of the customer within the payment provider * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ provider_customer_id?: string; /** * @description The type of payment provider code * @example stripe * @enum {string} */ payment_provider: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash"; /** * @description Code of the payment provider * @example Stripe Prod */ payment_provider_code?: string; provider_error?: string | { [key: string]: unknown; }; }; DunningCampaignFinishedObject: { /** * @description The customer external unique identifier (provided by your own application). * @example cus_0987654321 */ external_customer_id: string; /** * @description Identifier of the dunning campaign. * @example dun_code_1234 */ dunning_campaign_code: string; /** * @description The amount of the overdue balance, expressed in cents. * @example 120 */ overdue_balance_cents: number; /** * @description The currency of the balance. * @example EUR */ overdue_balance_currency: components["schemas"]["Currency"]; customer_external_id?: string; }; /** @description Core 11.16.0. One step of the dunning policy of an unpaid invoice. See [Dunning policy](/guides/billing/dunning). */ DunningStepObject: { /** * Format: uuid * @description Unique identifier of the unpaid invoice, created by Nozle. * @example 00000000-0000-4000-8000-000000000006 */ invoice_id: string; /** * @description Number of the unpaid invoice. * @example ACME-47DD-012-001 */ invoice_number: string; /** * Format: uuid * @description Unique identifier of the customer, created by Nozle. * @example 00000000-0000-4000-8000-000000000003 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application). * @example customer_123 */ external_customer_id?: string | null; /** * @description Code of the dunning campaign the invoice follows (the plan's, else the customer's, its billing entity's, then the default billing entity's). * @example block_after_grace */ dunning_campaign_code?: string; /** * @description The step that ran. `payment_failed` on day 0, `reminder` on round(grace × 3 / 7), `final_reminder` the day before the end, `end_action` on the last day, `resolved` once when the invoice no longer needs paying. * @example reminder * @enum {string} */ step: "payment_failed" | "reminder" | "final_reminder" | "end_action" | "resolved"; /** * @description Day of the timeline the step ran on, counted from `started_at`. * @example 3 */ day: number; /** * @description `unpaid_invoice_grace_days` of the plan behind the invoice (7 for an invoice without a plan). * @example 7 */ grace_days: number; /** * @description What happens on the last day of the grace. `block` refuses the customer's usage with `402` `customer_payment_overdue`. * @example block * @enum {string} */ end_action: "block"; /** * Format: date-time * @description Day 0 of the invoice's timeline. * @example 2026-10-20T09:00:00Z */ started_at: string; /** * Format: date-time * @description When the end action runs, `started_at` plus `grace_days`. * @example 2026-10-27T09:00:00Z */ deadline_at: string; /** * @description The next step of the timeline. `retry` only when the last decline is retried (a soft decline); after a hard decline or one that needs the customer, the next message step. `null` after the last one and on `resolved`. * @example retry * @enum {string|null} */ next_action?: "reminder" | "final_reminder" | "end_action" | "retry" | null; /** * Format: date-time * @description When `next_action` runs. * @example 2026-10-25T09:00:00Z */ next_action_at?: string | null; /** * @description Amount still owed on the invoice, in cents. * @example 4900 */ total_due_amount_cents: number; /** * @description Currency of the invoice. * @example USD */ currency: components["schemas"]["Currency"]; }; EventErrorsObject: { /** * @description HTTP status code. It will always be 422 * @example 422 */ status: number; /** * @description HTTP error description. It will always be "Unprocessable entity" * @example Unprocessable entity */ error: string; message: string | { [key: string]: unknown; }; event: components["schemas"]["EventObject"]; }; EventsErrorsObject: { /** * @description List of event transaction_id with an invalid code * @example [ * "transaction_1234567890" * ] */ invalid_code: string[]; /** * @description List of event transaction_id with a missing aggregation property * @example [ * "transaction_1234567890" * ] */ missing_aggregation_property: string[]; /** * @description List of event transaction_id with invalid filter values * @example [ * "transaction_1234567890" * ] */ invalid_filter_values: string[]; /** @deprecated */ missing_group_key: string[] | null; }; FeeTaxProviderErrorObject: { /** * @description Code of the tax provider * @example Stripe Prod */ tax_provider_code: string; /** * Format: uuid * @description Unique identifier assigned to the charge that the fee belongs to * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ charge_id: string | null; /** * @description Unique identifier assigned to the transaction. This field is specifically displayed when the fee type is `charge`. * @example transaction_1234567890 */ event_transaction_id: string | null; provider_error: string | { [key: string]: unknown; }; }; /** @description The lost dispute: the invoice, and the provider reason when there is one. */ InvoicePaymentDisputeLostObject: { invoice: components["schemas"]["InvoiceObjectExtended"]; /** @description Reason given by the provider. Only present when the provider sent one. */ provider_error?: string | { [key: string]: unknown; }; }; /** @description The invoice and the current state of its payment dispute. Only ids and statuses are sent. */ InvoicePaymentDisputeUpdatedObject: { invoice: components["schemas"]["InvoiceObjectExtended"]; dispute: { /** * @description Identifier of the dispute at the payment provider. * @example disp_Nozle0000000001 */ id: string; /** * @description The provider event that reported the dispute, without the `payment.dispute.` prefix. For Razorpay `created`, `under_review`, `action_required` or `won`. * @example action_required */ event: string; /** * @description Current status of the dispute at the provider, for example `open`, `under_review` or `won`. * @example open */ status: string; /** * @description Reason code the provider gives for the dispute. * @example fraudulent */ reason_code?: string | null; /** * @description Phase of the dispute, for example `chargeback`. * @example chargeback */ phase?: string | null; /** * @description Unix time by which you must answer the dispute, while you still can. Otherwise null. * @example 1793500000 */ respond_by?: number | null; }; }; InvoicePaymentFailureObject: { /** * Format: uuid * @description Unique identifier assigned to the invoice within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the invoice's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id: string; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description Unique identifier of the customer within the payment provider * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ provider_customer_id?: string; /** * @description The type of payment provider code * @example stripe * @enum {string} */ payment_provider: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash"; /** * @description Code of the payment provider * @example Stripe Prod */ payment_provider_code?: string; /** @description The provider's error. For a duplicate Stripe payment on an invoice that is already paid, an object with `message` and `error_code`: `duplicate_payment_refunded` (Nozle refunded the payment in full, refund reason `duplicate`), `duplicate_payment_refund_failed` (Stripe refused the refund; refund it by hand) or `duplicate_payment_requires_review` (the payment was still processing when the invoice was paid another way; not refunded automatically). */ provider_error?: string | { [key: string]: unknown; }; /** @description Extra detail. For a duplicate payment, `provider_payment_id` is the Stripe payment intent. */ error_details?: { [key: string]: unknown; }; }; IntegrationProviderErrorObject: { /** * Format: uuid * @description Unique identifier assigned to the integration within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the integration's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ integration_id: string; /** * @description The type of integration provider * @example anrok */ provider: string; /** * @description Unique code used to identify an integration connection. * @example anrok1 */ provider_code: string; provider_error: string | { [key: string]: unknown; }; }; PaymentProviderErrorObject: { /** * Format: uuid * @description Unique identifier assigned to the payment provider within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the payment provider's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ payment_provider_id: string; /** * @description The name of payment provider * @example Stripe Prod */ payment_provider_name: string; /** * @description Code of the payment provider * @example stripe */ payment_provider_code: string; /** * @description The source of the error * @example stripe * @enum {string|null} */ source: "stripe" | null; /** * @description The action that was being performed when the error occurred * @example payment_provider.register_webhook * @enum {string|null} */ action?: "payment_provider.register_webhook" | null; provider_error: string | { [key: string]: unknown; }; }; PaymentRequestPaymentFailureObject: { /** * Format: uuid * @description Unique identifier assigned to the payment request within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the payment request record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ payment_request_id: string; /** * @description List of unique identifiers assigned to the invoices within the Nozle application. These IDs are exclusively created by Nozle and serve as unique identifiers for the invoices records within the Nozle system. * @example [ * "1a901a90-1a90-1a90-1a90-1a901a901a90" * ] */ invoice_ids: string[]; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description Unique identifier of the customer within the payment provider * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ provider_customer_id?: string; /** * @description The type of payment provider code * @example stripe * @enum {string|null} */ payment_provider: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash" | null; /** * @description Code of the payment provider * @example Stripe Prod */ payment_provider_code?: string | null; provider_error?: string | { [key: string]: unknown; }; }; SubscriptionWithCustomerObject: components["schemas"]["SubscriptionObject"] & { plan: components["schemas"]["PlanObject"]; customer: components["schemas"]["CustomerObject"]; entitlements?: unknown[]; }; SubscriptionWithThresholdObject: components["schemas"]["SubscriptionObject"] & { plan: components["schemas"]["PlanObject"]; customer: components["schemas"]["CustomerObject"]; usage_threshold: components["schemas"]["UsageThresholdObject"]; /** @description List of usage thresholds applicable to this subscription. */ applicable_usage_thresholds?: components["schemas"]["ApplicableUsageThreshold"][]; }; WalletTransactionObjectExtended: components["schemas"]["WalletTransactionObject"] & { wallet?: components["schemas"]["WalletObject"]; }; WalletTransactionPaymentFailureObject: { /** * Format: uuid * @description Unique identifier assigned to the wallet transaction within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the wallet transaction's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ wallet_transaction_id: string; /** * Format: uuid * @description Unique identifier assigned to the customer within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the customer's record within the Nozle system. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * @description The customer external unique identifier (provided by your own application) * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ external_customer_id: string; /** * @description Unique identifier of the customer within the payment provider * @example 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba */ provider_customer_id?: string; /** * @description The type of payment provider code * @example stripe * @enum {string|null} */ payment_provider: "adyen" | "cashfree" | "gocardless" | "stripe" | "razorpay" | "flutterwave" | "moneyhash" | null; /** * @description Code of the payment provider * @example Stripe Prod */ payment_provider_code?: string | null; provider_error?: string | { [key: string]: unknown; }; }; CustomerPaymentProvidernErrorObject: components["schemas"]["CustomerPaymentProviderErrorObject"]; /** @description Error body of an Engine operation. Branch on `code` when it is present; `error` is a human-readable message. */ EngineError: { /** @example customer has multiple active subscriptions */ error: string; /** @example active_subscription_ambiguous */ code?: string; /** @description Request id to quote to support, when the Engine includes it. */ request_id?: string; }; /** @description Engine 2.22.0. A refusal of an OpenAI route of the LLM proxy, in OpenAI's error shape so the OpenAI SDK surfaces `error.code`. The top-level `code` is the same code. Before Engine 2.22.0 the body was `{"code", "error"}` with `error` a string. */ OpenAIProxyError: { error: { message: string; /** * @description `invalid_request_error` for `400` and `422`, `authentication_error` for `401`, `payment_required` for `402`, `permission_error` for `403`, `rate_limit_error` for `429`, else `api_error`. * @enum {string} */ type: "invalid_request_error" | "authentication_error" | "payment_required" | "permission_error" | "rate_limit_error" | "api_error"; /** @description The Nozle error code, for example `customer_payment_overdue`. */ code: string; }; /** @description The same code, kept at the top level. */ code: string; }; /** @description Engine 2.22.0. A refusal of an Anthropic route of the LLM proxy, in Anthropic's error shape so the Anthropic SDK surfaces it. The top-level `code` is the same code. Before Engine 2.22.0 the body was `{"code", "error"}` with `error` a string. */ AnthropicProxyError: { /** @enum {string} */ type: "error"; error: { /** * @description `invalid_request_error` for `400` and `422`, `authentication_error` for `401`, `billing_error` for `402`, `permission_error` for `403`, `rate_limit_error` for `429`, else `api_error`. * @enum {string} */ type: "invalid_request_error" | "authentication_error" | "billing_error" | "permission_error" | "rate_limit_error" | "api_error"; message: string; /** @description The Nozle error code, for example `customer_payment_overdue`. */ code: string; }; /** @description The same code, kept at the top level. */ code: string; }; /** @description Error body produced by Core and forwarded unchanged by Engine. Checkout errors always carry `status`, `error` and `code`; some conflict responses of other routes carry only `code`. Validation failures carry `error_details`, an object whose keys are field names and whose values are arrays of error codes. */ BillingCoreError: { /** @example 409 */ status?: number; /** @example Conflict */ error?: string; /** @example plan_change_quote_changed */ code?: string; error_details?: { [key: string]: unknown; }; }; /** @description Either an Engine error (`{error, code?, request_id?}`) or a Core error forwarded unchanged (`{status, error, code, error_details?}`). */ BillingEngineOrCoreError: components["schemas"]["EngineError"] | components["schemas"]["BillingCoreError"]; /** @description Most recently started active subscription of the customer. Built from Engine's billing database, not from Core's API. The usage fields (`events_used` to `plan_limits`) appear only in Nozle's status of your own workspace on its Nozle plan (shown under Settings > Billing settings > Plan and in GraphQL `nozlePlanStatus`); the status of your customers never includes them. */ BillingStatusResponse: { /** * @description Plan code of the active subscription. * @example pro */ plan: string; /** * @description The plan's display name. Falls back to the plan code when the plan has no name. * @example Pro */ planName: string; /** * @description Always `active`: only active subscriptions are read. * @enum {string} */ status: "active"; /** * @description The plan's billing interval. * @enum {string} */ interval: "weekly" | "monthly" | "yearly" | "quarterly" | "semiannual"; /** * Format: int64 * @description Plan base amount in the currency's minor unit. * @example 4900 */ amount_cents: number; /** @example USD */ currency: string; /** * Format: int64 * @description Workspace plan status only. Events reported in the current billing period, across a plan change in that period. * @example 60000 */ events_used?: number; /** * Format: int64 * @description Workspace plan status only. Events included in the plan; null when the plan has none. * @example 50000 */ events_included?: number | null; /** * @description Workspace plan status only. `events_used` / `events_included` in percent, one decimal; null without a limit. * @example 120 */ events_used_percent?: number | null; /** * Format: int64 * @description Workspace plan status only. Tracked MRR of every currency, in USD cents at the latest ECB rates; null while a currency has no rate. * @example 0 */ mrr_tracked_usd_cents?: number | null; /** * Format: int64 * @description Workspace plan status only. The plan's MRR limit in USD cents; null when the plan has none. * @example 500000 */ mrr_limit_usd_cents?: number | null; /** * @description Workspace plan status only. `mrr_tracked_usd_cents` / `mrr_limit_usd_cents` in percent, one decimal; null without a limit or a rate. * @example 0 */ mrr_used_percent?: number | null; /** @description Workspace plan status only. The plan's limits. */ plan_limits?: { /** * Format: int64 * @description Included events. * @example 50000 */ events?: number | null; /** * Format: int64 * @description MRR limit in USD cents. * @example 500000 */ mrr_cents?: number | null; }; }; BillingInvoiceSummary: { /** Format: uuid */ id: string; /** @example ACME-202610-001 */ number: string; /** * @description Only the statuses Core's API shows, other than draft. Drafts and invoices still being generated are never returned. Whether the invoice is paid is in `payment_status`. * @enum {string} */ status: "finalized" | "voided" | "failed" | "pending"; /** * @description `succeeded` means the invoice is paid. * @enum {string} */ payment_status: "pending" | "succeeded" | "failed" | "unknown"; /** * @description `other` is a type Engine does not know. * @enum {string} */ invoice_type: "subscription" | "add_on" | "credit" | "one_off" | "advance_charges" | "progressive_billing" | "other"; /** * Format: int64 * @description Invoice total in the currency's minor unit. */ amount_cents: number; /** * @description Invoice currency; `usd` when the invoice has none. * @example USD */ currency: string; /** Format: date */ issuing_date: string | null; /** Format: date */ payment_due_date: string | null; /** Format: date-time */ created_at: string; }; BillingInvoiceListResponse: { /** @description Newest first, at most 50, drafts excluded. Empty array when the customer has none. */ invoices: components["schemas"]["BillingInvoiceSummary"][]; }; BillingUpgradeRequest: { /** * @description Target plan code. * @example starter_monthly */ plan_code: string; /** * @description External customer ID. Required unless `organization_id` is sent. * @example customer_123 */ customer_id?: string; /** * @deprecated * @description Legacy fallback used as `customer_id` when `customer_id` is empty. */ organization_id?: string; /** @description External ID of the subscription to change. Optional; selects the subscription as for `/can`. */ subscription_id?: string; /** @description External ID of the Entity whose subscription to change. Optional; selects the subscription as for `/can`. */ entity_id?: string; }; /** @description Send `plan_code`, or `plan_family_code` with `interval` (and optional `currency`). Neither returns `400`. */ BillingSubscribeRequest: { /** * @description External ID of an existing customer. * @example customer_123 */ customer_id: string; /** @example pro */ plan_code?: string; /** * @description Core 11.10.0, Engine 2.21.0. The subscription's external ID is then `sub--`. Sells a plan family instead of `plan_code`; Nozle picks the family's current plan for `interval` and `currency`. Cannot be combined with `plan_code` (`422`, `plan_family_code: [incompatible_with_plan_code]`). An unknown family returns `404 plan_family_not_found`. See [Multi-currency pricing](/guides/billing/multi-currency-pricing#checkout-and-subscribe-by-family). * @example pro */ plan_family_code?: string; /** * @description Required with `plan_family_code` (`interval: [value_is_mandatory]` without it, `[value_is_invalid]` for an unknown value). * @example yearly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description With `plan_family_code`, the ISO 4217 code of the plan to sell. Without it, the currency of the subscription being changed, else the customer's locked currency, else the family's default currency. A currency the family does not sell for that interval returns `422` with `currency: [currency_not_offered]`. * @example EUR */ currency?: string; /** * @description Optional. The version of `plan_code` to subscribe to. Without it, the customer gets the current version. Core's rules apply (see `plan_version` on `POST /subscriptions`). * @example 1 */ plan_version?: number; }; /** @description Core's subscription response with two fields added by Engine. */ BillingSubscribeResponse: components["schemas"]["Subscription"] & { /** * @description External subscription ID, `sub--`. * @example sub-customer_123-pro */ subscription_id: string; /** * @description Copy of `subscription.status`. * @example active */ status: string; }; /** @description Either `invoice_id` (pay an existing invoice), or `plan_code` (or `plan_family_code` with `interval`) with a customer, is required. */ BillingCheckoutRequest: { /** * @description External customer ID. Required with `plan_code` or `plan_family_code`. Falls back to the customer of trusted internal authentication, then to `organization_id`. * @example customer_123 */ customer_id?: string; /** * @description Plan to check out. Required unless `invoice_id` or `plan_family_code` is sent. * @example growth */ plan_code?: string; /** * @description Core 11.10.0, Engine 2.21.0. Sells a plan family instead of `plan_code`; Nozle picks the family's current plan for `interval` and `currency`. Cannot be combined with `plan_code` (`422`, `plan_family_code: [incompatible_with_plan_code]`). An unknown family returns `404 plan_family_not_found`. See [Multi-currency pricing](/guides/billing/multi-currency-pricing#checkout-and-subscribe-by-family). * @example pro */ plan_family_code?: string; /** * @description Required with `plan_family_code` (`interval: [value_is_mandatory]` without it, `[value_is_invalid]` for an unknown value). * @example yearly * @enum {string} */ interval?: "weekly" | "monthly" | "quarterly" | "semiannual" | "yearly"; /** * @description With `plan_family_code`, the ISO 4217 code of the plan to sell. Without it, the currency of the subscription being changed, else the customer's locked currency, else the family's default currency. A currency the family does not sell for that interval returns `422` with `currency: [currency_not_offered]`. * @example EUR */ currency?: string; /** * @deprecated * @description Legacy fallback for `customer_id`. */ organization_id?: string; /** * Format: uri * @description Absolute HTTPS URL on one of the organization's allowed origins (`checkout_return_origins`). May contain the literal `{CHECKOUT_SESSION_ID}`, which Stripe replaces with the Checkout Session ID. Defaults to `success_url`, then to the organization's default return URL. */ return_url?: string; /** * Format: uri * @description Where Stripe sends a customer who leaves the hosted page without paying. Validated like `return_url`. Defaults to the return URL. Accepted by `POST /checkout` only; the Entity subscription endpoints take `return_url` alone. */ cancel_url?: string; /** * Format: uri * @description Backward-compatible alias for `return_url`. */ success_url?: string; /** @description Nozle invoice to collect payment for instead of starting a plan checkout. Cannot be combined with `subscription_id`. From Core 11.16.0 the hosted Stripe page offers only the customer's payment methods, a card saved while paying is recorded as the customer's payment method, and a `return_url` replaces an open Checkout Session that returns elsewhere. */ invoice_id?: string; /** @description Customer Entity whose own subscription is checked out. Cannot be combined with `subscription_id`. */ external_entity_id?: string; /** * @description Razorpay only: set up auto-pay with the payment of a subscription invoice. The result is `hosted` with `payment_url`, Nozle's auto-pay setup page, instead of a `razorpay` order. A plan change that leaves an amount due answers `422 razorpay_mandate_registration_unavailable` instead. * @default false */ register_mandate: boolean; /** @description External ID of the active subscription to change. Forwarded to Core as `external_subscription_id`. Required when the customer has several active subscriptions. */ subscription_id?: string; /** @description Opaque signed quote from `POST /subscriptions/preview`. Core requires `subscription_id` and an `Idempotency-Key` with it. */ quote_id?: string; }; /** @description Result of a checkout. The fields present depend on `type`. `hosted` (Stripe): `url`, `payment_url` (the same value), `checkout_id` (the Stripe Checkout Session ID), `amount_cents`, `currency`, `expires_at`, and `invoice_id` or `plan_upgrade_intent_id`. `hosted` (Razorpay mandate checkout, `register_mandate`): `payment_url` (Nozle's auto-pay setup page), `checkout_id` (to poll), `amount_cents`, `currency`, `expires_at`, `invoice_id`. `razorpay`: `checkout_id`, `key_id`, `order_id`, `amount_cents`, `currency`, `expires_at`, and `invoice_id` or `plan_upgrade_intent_id`. `processing`: `checkout_id` and `status`. `completed`: `status`, `payment_source`, `subscription_id`, `plan_code`, `invoice_id`, `amount_cents`, `currency` (an immediate configured downgrade instead carries the settlement fields of a transition result). `scheduled`: `status`, `subscription_id` (the pending subscription), `plan_code`, `transition_direction`, `transition_policy`, `effective_at`. Entity checkouts add `external_entity_id` and `external_subscription_id`. There is no `stripe` result and no client secret. */ BillingCheckoutResult: { /** @enum {string} */ type: "hosted" | "razorpay" | "processing" | "completed" | "scheduled"; /** @description `succeeded` for `completed`; the pending subscription status for `scheduled`; the internal operation status for `processing`. */ status?: string; /** * Format: uri * @description `hosted` only: the Stripe-hosted Checkout page. Redirect the customer to it. */ url?: string; /** @description For `hosted`, the Stripe Checkout Session ID (`cs_...`); it is not a status ID (poll a paid upgrade with `plan_upgrade_intent_id`). For Razorpay, the operation ID (UUID), used with `GET /checkout/{id}` and `POST /checkout/{id}/verify`. */ checkout_id?: string; /** @description Public Razorpay key ID. */ key_id?: string; /** @description Razorpay order ID. */ order_id?: string; /** @description Razorpay customer ID. Only on orders of earlier mandate checkouts; a mandate checkout now answers `hosted`. */ customer_id?: string; recurring?: boolean; mandate_max_amount_cents?: number; /** Format: uri */ payment_url?: string; /** Format: date-time */ expires_at?: string | null; /** Format: uuid */ invoice_id?: string | null; /** * Format: uuid * @description Paid upgrades: the pending upgrade. Poll it with `GET /checkout/{id}` using the subscription scope. */ plan_upgrade_intent_id?: string; amount_cents?: number; currency?: string; /** @enum {string} */ payment_source?: "credits" | "none"; /** * Format: uuid * @description Core subscription UUID (for `scheduled`, the pending subscription). */ subscription_id?: string; plan_code?: string; /** @enum {string} */ transition_direction?: "upgrade" | "downgrade"; /** @enum {string} */ transition_policy?: "prorate_keep_anchor" | "full_term_reset_anchor" | "next_period"; /** * Format: date-time * @description RFC 3339 with microseconds, in the customer's timezone offset. */ effective_at?: string; external_entity_id?: string; external_subscription_id?: string; }; BillingCheckoutStatus: { /** Format: uuid */ checkout_id: string; /** @enum {string} */ provider: "stripe" | "razorpay"; /** @enum {string} */ status: "awaiting_payment" | "processing" | "succeeded" | "failed" | "expired" | "needs_review"; /** @enum {string} */ fulfillment_status: "pending" | "processing" | "succeeded"; amount_cents?: number; currency?: string; /** Format: uuid */ invoice_id?: string | null; /** @description Resumable checkout, present when the payment can still be completed or the upgrade was applied. */ checkout?: components["schemas"]["BillingCheckoutResult"]; }; BillingRazorpayVerifyRequest: { razorpay_order_id: string; razorpay_payment_id: string; razorpay_signature: string; }; BillingPlanChangePreviewRequest: { /** * @description External customer ID. Required (falls back only to the customer of trusted internal authentication). * @example customer_123 */ customer_id?: string; /** * @description External ID of the subscription to change. Optional, but Core answers `409 subscription_selection_required` when it is absent and the customer has several active subscriptions. * @example subscription_123 */ subscription_id?: string; /** @example pro_monthly */ plan_code: string; }; /** @description Signed plan-change quote from Core. Monetary `*_cents` fields are integers in the minor unit; `credit`, `debit` and `net` are the same amounts in major units. */ BillingPlanChangeQuote: { /** @description Opaque signed quote. Forward it unchanged. */ quote_id: string; /** * Format: uuid * @description Core UUID of the current subscription. */ subscription_id?: string; external_subscription_id?: string; credit?: number; debit?: number; net?: number; currency: string; /** Format: date-time */ next_billing_date?: string | null; /** * Format: date-time * @description Camel-case alias of `next_billing_date`. */ nextBillingDate?: string | null; /** Format: date */ invoice_issuing_date?: string | null; /** @description Credit applied to this change; `net_amount_cents` is debit minus credit. */ credit_amount_cents?: number; /** @description Balance left on the credit notes the change issues, used on later invoices. */ credit_remaining_amount_cents?: number; /** @description Amount the credit notes the change issues refund. */ refund_amount_cents?: number; debit_amount_cents?: number; net_amount_cents?: number; amount_due_now_cents?: number; amount_due_at_effective_cents?: number; /** @enum {string} */ transition_direction: "upgrade" | "downgrade"; /** @enum {string} */ timing: "immediate" | "end_of_period"; /** @enum {string} */ transition_policy?: "prorate_keep_anchor" | "full_term_reset_anchor" | "next_period"; /** @enum {string} */ billing_anchor?: "keep_anchor" | "reset_anchor"; /** @enum {string} */ proration_behavior?: "prorate_immediately" | "none"; /** @enum {string} */ credit_action?: "credit" | "refund" | "offset" | "none"; /** @enum {string} */ refund_mode?: "prorated" | "full"; /** @enum {string} */ final_invoice_action?: "generate" | "skip"; /** * Format: date-time * @description RFC 3339 with microseconds in the customer's timezone offset. */ effective_at: string; /** Format: date-time */ renewal_at?: string | null; }; BillingPlanSummary: { code: string; name: string; amount_cents: number; currency: string; /** @example monthly */ interval: string; }; BillingSubscriptionOptionsResponse: { subscription: { /** Format: uuid */ id: string; external_id: string; plan_code: string; plan: components["schemas"]["BillingPlanSummary"]; /** @example active */ status: string; /** Format: date-time */ ending_at: string | null; }; /** @description Pending scheduled change, or null. */ pending_change: { /** * Format: uuid * @description Pending subscription UUID; send it as `pending_subscription_id` to withdraw. */ id: string; plan_code: string; name: string; plan: components["schemas"]["BillingPlanSummary"]; /** Format: date-time */ effective_at: string; } | null; /** @description Plans with a resolvable transition policy. Empty when the subscription is externally billed, is scheduled to end, has a pending change, or has an unresolved upgrade checkout. Downgrades appear only with `end_of_period` timing and `keep_anchor`. */ eligible_plans: (components["schemas"]["BillingPlanSummary"] & { /** @enum {string} */ direction: "upgrade" | "downgrade"; /** @enum {string} */ timing: "immediate" | "end_of_period"; })[]; /** @description Latest upgrade checkout for this subscription, or null. */ checkout: { /** Format: uuid */ id: string; status: string; plan_code: string; } | null; }; /** @description Unknown fields are rejected with `400`. Values are trimmed before validation. Engine forwards the request to Core inside `subscription_transition`, renaming `customer_id` and `subscription_id` to `external_customer_id` and `external_subscription_id`. */ BillingTransitionRequest: { /** @description External customer ID. May be omitted only with trusted internal authentication that carries a customer. */ customer_id: string; /** @description External subscription ID; must belong to the customer. */ subscription_id: string; /** @enum {string} */ operation: "cancel" | "downgrade" | "uncancel"; /** @enum {string} */ timing?: "end_of_period" | "immediate"; /** @description Required for `downgrade`; must be empty for `cancel` and `uncancel`. */ target_plan_code?: string; /** @enum {string} */ billing_anchor?: "keep_anchor" | "reset_anchor"; /** @enum {string} */ proration_behavior?: "prorate_immediately" | "none"; /** @enum {string} */ credit_action?: "credit" | "refund" | "offset" | "none"; /** * @description `full` requires `credit_action: refund`. * @enum {string} */ refund_mode?: "prorated" | "full"; /** @enum {string} */ final_invoice_action?: "generate" | "skip"; /** * Format: date-time * @description Only for `operation: cancel` with `timing: end_of_period`. Apply fails with `409 subscription_cancellation_date_changed` when it no longer matches. */ expected_effective_at?: string; /** @description Signed quote; accepted only for `downgrade`. */ quote_id?: string; }; BillingTransitionPreview: { /** @enum {string} */ operation?: "cancel" | "downgrade" | "uncancel"; timing?: string | null; credit_action?: string | null; refund_mode?: string | null; billing_anchor?: string | null; proration_behavior?: string | null; final_invoice_action?: string | null; /** Format: date-time */ effective_at?: string; /** Format: date-time */ renewal_at?: string | null; credit_amount_cents?: number; refund_amount_cents?: number; offset_amount_cents?: number; amount_due_cents?: number; currency?: string | null; }; BillingTransitionPreviewResponse: { subscription_transition: components["schemas"]["BillingTransitionPreview"]; }; /** @description Recorded settlement snapshot. Null fields are omitted. */ BillingTransitionResult: { /** * Format: uuid * @description Settlement record ID. */ id: string; /** @enum {string} */ operation: "cancel" | "downgrade" | "uncancel"; timing?: string; credit_action?: string; refund_mode?: string; billing_anchor?: string; proration_behavior?: string; final_invoice_action?: string; /** * Format: date-time * @description For end-of-period cancellation, the subscription's `ending_at`. */ effective_at: string; /** Format: uuid */ subscription_id?: string; external_subscription_id?: string; plan_code?: string; status?: string; /** Format: uuid */ credit_note_id?: string; credit_amount_cents?: number; refund_amount_cents?: number; offset_amount_cents?: number; /** Format: uuid */ invoice_id?: string; amount_due_cents?: number; currency?: string; /** @description True when the same Idempotency-Key returned an earlier result. */ replayed: boolean; }; BillingTransitionResultResponse: { subscription_transition: components["schemas"]["BillingTransitionResult"]; }; BillingWithdrawRequest: { customer_id: string; /** @description External ID of the active subscription. */ subscription_id: string; /** * Format: uuid * @description Core UUID of the pending subscription (`pending_change.id` from options). */ pending_subscription_id: string; }; BillingWithdrawResponse: { subscription: { /** Format: uuid */ id?: string; external_id?: string; plan_code?: string; status?: string; }; /** Format: uuid */ withdrawn_pending_subscription_id: string; replayed: boolean; }; BillingPlanTransitionPolicyInput: { /** @description On a new policy, omitted fields take their defaults. On an existing policy, omitted fields keep their current values. */ plan_transition_policy: { /** * @description Required when creating a policy. * @enum {string} */ direction?: "upgrade" | "downgrade"; /** * @description Preset summary. Sent alone on a new policy, it sets the other fields. Otherwise Core derives it from the fields. * @enum {string} */ policy?: "prorate_keep_anchor" | "full_term_reset_anchor" | "next_period"; /** * @description Default `immediate`. * @enum {string} */ timing?: "immediate" | "end_of_period"; /** * @description Default `keep_anchor`. `reset_anchor` requires `immediate` timing. * @enum {string} */ billing_anchor?: "keep_anchor" | "reset_anchor"; /** * @description Default `prorate_immediately`. Must be `none` with `end_of_period` timing. * @enum {string} */ proration_behavior?: "prorate_immediately" | "none"; /** * @description Default `none`. Must be `none` with `end_of_period` timing; `offset` requires `final_invoice_action: generate`. * @enum {string} */ credit_action?: "credit" | "refund" | "offset" | "none"; /** * @description Default `prorated`. `full` requires `credit_action: refund`. * @enum {string} */ refund_mode?: "prorated" | "full"; /** * @description Default `generate`. * @enum {string} */ final_invoice_action?: "generate" | "skip"; }; }; BillingPlanTransitionPolicy: { /** Format: uuid */ nozle_id: string; source_plan_code: string; target_plan_code: string; /** @enum {string} */ direction: "upgrade" | "downgrade"; /** @enum {string} */ policy: "prorate_keep_anchor" | "full_term_reset_anchor" | "next_period"; /** @enum {string} */ timing: "immediate" | "end_of_period"; /** @enum {string} */ billing_anchor: "keep_anchor" | "reset_anchor"; /** @enum {string} */ proration_behavior: "prorate_immediately" | "none"; /** @enum {string} */ credit_action: "credit" | "refund" | "offset" | "none"; /** @enum {string} */ refund_mode: "prorated" | "full"; /** @enum {string} */ final_invoice_action: "generate" | "skip"; /** Format: date-time */ created_at: string; /** Format: date-time */ updated_at: string; }; BillingPlanTransitionPolicyResponse: { plan_transition_policy: components["schemas"]["BillingPlanTransitionPolicy"]; }; /** @description One version of a plan code. */ PlanVersion: { /** * Format: uuid * @description The id of the plan row of this version. */ nozle_id: string; version: number; /** @description Whether new subscriptions get this version. */ is_current: boolean; /** Format: date-time */ created_at: string; /** @description The base price of this version. */ amount_cents: number; /** @example USD */ amount_currency: string; /** @description Active subscriptions billed on this version. */ active_subscriptions_count: number; }; PlanVersionList: { versions: components["schemas"]["PlanVersion"][]; }; PlanVersionMigrationInput: { /** @description The version whose active subscriptions move. */ from_version: number; /** @description The version they move to. Defaults to the current version. */ to_version?: number; /** * @description Only read when starting a migration. Without it, starting is refused with `422` `price_increase_not_allowed` when any subscription would pay more, or pass its auto-pay limit. Check the preview first. * @default false */ allow_price_increase: boolean; }; /** @description The outcome of a migration for one subscription. */ PlanVersionMigrationItem: { external_subscription_id: string; /** * @description `succeeded`: the move is scheduled for the end of the period (or has happened). `canceled`: the migration was canceled before the move started. * @enum {string} */ status: "succeeded" | "skipped" | "failed" | "canceled"; /** @enum {string|null} */ skip_reason?: "already_on_version" | "canceling" | "custom_pricing" | "different_billing" | "external_billing" | "in_trial" | "not_active" | "open_checkout" | "pending_plan_change" | null; /** @description Why the move failed. A rerun retries it. */ error?: string | null; /** * Format: date-time * @description When the subscription starts on the new version. */ effective_at?: string | null; /** * @description For a scheduled move (`status: succeeded`): `pending` until the subscription starts on the new version, `moved` once it has, `canceled` when the move was undone because the subscription ended first. `null` for other items. * @enum {string|null} */ move_status?: "pending" | "moved" | "canceled" | null; }; PlanVersionMigration: { /** Format: uuid */ nozle_id: string; plan_code: string; from_version: number; to_version: number; /** * @description `succeeded` once every subscription was handled: each move is then scheduled for the end of its period. * @enum {string} */ status: "running" | "succeeded" | "completed_with_errors" | "failed" | "canceled"; /** @description Active subscriptions on `from_version` when the migration started. */ matched_count: number; succeeded_count: number; skipped_count: number; failed_count: number; /** Format: date-time */ started_at?: string | null; /** Format: date-time */ finished_at?: string | null; /** Format: date-time */ canceled_at?: string | null; /** Format: date-time */ created_at: string; /** @description One per subscription. Only in `GET /plans/{code}/version-migrations/{id}`. */ items?: components["schemas"]["PlanVersionMigrationItem"][]; }; PlanVersionMigrationResponse: { plan_version_migration: components["schemas"]["PlanVersionMigration"]; }; PlanVersionMigrationList: { plan_version_migrations: components["schemas"]["PlanVersionMigration"][]; }; PlanVersionMigrationPreviewItem: { external_subscription_id: string; external_customer_id?: string; /** @enum {string} */ outcome: "move" | "skip"; /** @description Why the subscription would stay, when `outcome` is `skip` (see `PlanVersionMigrationItem.skip_reason`). */ skip_reason?: string | null; /** * Format: date * @description The day the subscription would start on the new version. */ effective_on?: string | null; current_amount_cents?: number; new_amount_cents?: number; /** * @description What the move does to the price. `increase` when the plan amount goes up. `undeterminable` when the plan amount does not go up but usage, fixed or commitment pricing differs, so the total depends on future usage. `null` for a skipped subscription, which keeps its price. * @enum {string|null} */ price_change?: "increase" | "decrease" | "same" | "undeterminable" | null; /** @description `true` when `price_change` is `increase`. Starting the migration needs `allow_price_increase` while any item has it. */ price_increase?: boolean; /** @description `true` when the new amount is above the customer's auto-pay limit. Starting the migration needs `allow_price_increase` while any item has it. */ mandate_cap_exceeded?: boolean; }; PlanVersionMigrationPreview: { plan_code: string; from_version: number; to_version: number; items: components["schemas"]["PlanVersionMigrationPreviewItem"][]; }; PlanVersionMigrationPreviewResponse: { plan_version_migration_preview: components["schemas"]["PlanVersionMigrationPreview"]; }; BillingPlanTransitionPolicyList: { plan_transition_policies: components["schemas"]["BillingPlanTransitionPolicy"][]; }; BillingEntitySubscription: { external_customer_id: string; external_entity_id: string; /** @description Stable Nozle-generated subscription identity of the Entity. */ external_subscription_id: string; /** * @description Status of the current (or incomplete) subscription, or `unsubscribed`. * @example active */ status: string; /** @example nozle */ billing_authority?: string | null; /** Format: date-time */ credit_import_completed_at?: string | null; current_plan?: { code?: string; name?: string; interval?: string; amount_cents?: number; amount_currency?: string; status?: string; /** * Format: date-time * @description The subscription's `scheduled_change_at`, else `started_at`, else `subscription_at`. */ effective_at?: string | null; } | null; pending_plan?: { code?: string; name?: string; interval?: string; amount_cents?: number; amount_currency?: string; status?: string; /** * Format: date-time * @description The subscription's `scheduled_change_at`, else `started_at`, else `subscription_at`. */ effective_at?: string | null; } | null; /** @enum {string|null} */ billing_time?: "anniversary" | "calendar" | null; /** Format: date-time */ subscription_at?: string | null; /** Format: date-time */ started_at?: string | null; /** Format: date-time */ current_period_start?: string | null; /** Format: date-time */ current_period_end?: string | null; /** Format: date-time */ ending_at?: string | null; /** Format: date-time */ canceled_at?: string | null; cancel_at_period_end?: boolean | null; /** Format: date-time */ created_at?: string; /** Format: date-time */ updated_at?: string; }; BillingEntitySubscriptionResponse: { entity_subscription: components["schemas"]["BillingEntitySubscription"]; }; BillingEntitySubscriptionList: { /** @description Ordered by `external_entity_id`. */ entity_subscriptions: components["schemas"]["BillingEntitySubscription"][]; }; /** @description Flat body (no root key). The customer and Entity come from the path. */ BillingEntityCheckoutRequest: { /** @example pro_monthly */ plan_code?: string; /** * @description Initial subscription only. * @enum {string} */ billing_time?: "anniversary" | "calendar"; /** * Format: uri * @description May contain the literal `{CHECKOUT_SESSION_ID}`. */ return_url?: string; /** * Format: uri * @description Alias for `return_url`. */ success_url?: string; invoice_id?: string; external_subscription_id?: string; quote_id?: string; register_mandate?: boolean; }; /** @description Flat body (no root key). */ BillingEntityCancelRequest: { /** @enum {string} */ timing?: "immediate" | "end_of_period"; /** * @description Send it explicitly; a plan billed in arrears without it fails with `422 not_supported_for_pay_in_arrears`. * @enum {string} */ credit_action?: "credit" | "refund" | "offset" | "none"; /** @enum {string} */ refund_mode?: "prorated" | "full"; /** @enum {string} */ final_invoice_action?: "generate" | "skip"; }; BillingEntityCancelResponse: { entity_subscription: components["schemas"]["BillingEntitySubscription"]; subscription_transition: components["schemas"]["BillingTransitionResult"]; }; BillingEntityCheckoutBatchRequest: { entity_subscription_checkout: { /** * @description Defaults to the organization's billing alignment. * @enum {string} */ billing_time?: "anniversary" | "calendar"; /** * Format: uri * @description May contain the literal `{CHECKOUT_SESSION_ID}`. */ return_url?: string; items: { external_entity_id: string; plan_code: string; }[]; }; }; BillingEntityCheckoutBatch: { /** Format: uuid */ id: string; /** * @description Razorpay results override the default `hosted` (Stripe) type with the Razorpay checkout's own `type` and fields. * @enum {string} */ type: "hosted" | "razorpay" | "processing" | "completed"; /** * @description Batch status. * @enum {string} */ status: "pending" | "open" | "completed" | "failed" | "expired"; /** * Format: uri * @description `hosted` only: the Stripe-hosted Checkout page. */ url?: string | null; /** Format: uri */ payment_url?: string | null; /** Format: uuid */ invoice_id?: string | null; amount_cents?: number; currency?: string; replayed: boolean; /** Format: date-time */ expires_at?: string | null; /** Format: uuid */ checkout_id?: string; key_id?: string; order_id?: string; items: { external_entity_id?: string; external_subscription_id?: string; plan_code?: string; subscription_status?: string; }[]; }; BillingEntityCheckoutBatchResponse: { entity_subscription_checkout: components["schemas"]["BillingEntityCheckoutBatch"]; }; BillingStateImportRequest: { billing_state_import: { /** @default false */ dry_run: boolean; /** @description Import an Entity subscription for this Entity. */ external_entity_id?: string; subscription: { plan_code: string; /** @enum {string} */ status: "active"; /** @enum {string} */ billing_authority: "external"; /** @description Your source-system reference. */ external_reference: string; /** * Format: date-time * @description Inclusive. */ current_period_start: string; /** * Format: date-time * @description Exclusive; the period must contain now and span exactly one plan interval. */ current_period_end: string; }; }; }; BillingStateImport: { /** * Format: uuid * @description Absent on a first dry run. */ id?: string; /** * @description `validated` for a dry run. * @enum {string} */ status: "completed" | "validated"; dry_run: boolean; external_customer_id: string; external_entity_id?: string; subscription: { /** Format: uuid */ id?: string; external_subscription_id?: string; external_reference?: string; plan_code?: string; /** @enum {string} */ status?: "active"; /** @enum {string} */ billing_authority?: "external"; credit_import_required?: boolean; /** Format: date-time */ current_period_start?: string; /** Format: date-time */ current_period_end?: string; /** @enum {boolean} */ invoice_created?: false; }; replayed: boolean; }; BillingStateImportResponse: { billing_state_import: components["schemas"]["BillingStateImport"]; }; /** * @description One active or scheduled credit source. * @example { * "id": "bf659149-0d70-4d2a-8a7b-a4569cc742eb", * "entity_id": null, * "parent_source_id": null, * "scope": "customer", * "transferable": false, * "returnable": false, * "type": "subscription_grant", * "reference": "subscription:b85038ab-8ef6-45a8-9643-43b24a891362:period:2026-07-01T00:00:00Z:system:c15f2949-7df6-4f05-89af-3f1b0bc82189:customer:92087f4d-b90c-41ca-8406-5bdbc199810a", * "subscription_id": "b85038ab-8ef6-45a8-9643-43b24a891362", * "initial": "625.5", * "remaining": "625.5", * "valid_from": "2026-07-01T00:00:00Z", * "expires_at": "2026-08-01T00:00:00Z", * "priority": 100, * "status": "active", * "available": true * } */ CreditsBalanceSource: { /** @description Source identifier. */ id: string; /** @description External Entity ID the source is scoped to; `null` for a customer-level source. */ entity_id: string | null; /** @description Source this one was split from (for example an Entity allocation of a top-up); `null` otherwise. */ parent_source_id: string | null; /** * @description `customer` for the shared pool, `entity` for an Entity-owned source. * @enum {string} */ scope: "customer" | "entity"; /** @description `true` when the source is an available `top_up` of an active Credit System and can be allocated to an Entity. */ transferable: boolean; /** @description Whether an Entity allocation can be returned to the customer pool. Always `false` on customer-level sources. */ returnable: boolean; /** * @description Source type. * @enum {string} */ type: "subscription_grant" | "top_up" | "manual_grant" | "adjustment" | "allocated_top_up"; /** @description Stable reference of the grant or payment that created the source. Treat it as opaque. */ reference: string; /** @description Subscription of a subscription grant; `null` otherwise. */ subscription_id: string | null; /** @description Amount when the source was created, as a decimal string without trailing zeros. */ initial: string; /** @description Amount not yet consumed, as a decimal string. */ remaining: string; /** @description Credits of this source reserved by open holds, as a decimal string (Engine 2.34.0+). */ held?: string; /** * Format: date-time * @description Time the source becomes usable. */ valid_from: string; /** * Format: date-time * @description Expiry time, or `null` if the source never expires. */ expires_at: string | null; /** @description Tie-breaker for sources with the same expiry; the lower value is consumed first. */ priority: number; /** @description Source status. Only `active` sources are returned. */ status: string; /** @description `true` when `valid_from` is not after `as_of`. */ available: boolean; }; /** * @description A customer's balance in one Credit System. * @example { * "customer_id": "customer_123", * "credit_system": "ai_credits", * "credit_system_id": "c15f2949-7df6-4f05-89af-3f1b0bc82189", * "credit_system_name": "AI Credits", * "unit_name": "credit", * "system_status": "active", * "available": "625.5", * "as_of": "2026-07-20T12:00:00.750Z", * "sources": [ * { * "id": "bf659149-0d70-4d2a-8a7b-a4569cc742eb", * "entity_id": null, * "parent_source_id": null, * "scope": "customer", * "transferable": false, * "returnable": false, * "type": "subscription_grant", * "reference": "subscription:b85038ab-8ef6-45a8-9643-43b24a891362:period:2026-07-01T00:00:00Z:system:c15f2949-7df6-4f05-89af-3f1b0bc82189:customer:92087f4d-b90c-41ca-8406-5bdbc199810a", * "subscription_id": "b85038ab-8ef6-45a8-9643-43b24a891362", * "initial": "625.5", * "remaining": "625.5", * "valid_from": "2026-07-01T00:00:00Z", * "expires_at": "2026-08-01T00:00:00Z", * "priority": 100, * "status": "active", * "available": true * } * ] * } */ CreditsCustomerBalance: { /** @description External customer ID. */ customer_id: string; /** @description Credit System code. */ credit_system: string; /** @description Credit System identifier. */ credit_system_id: string; /** @description Display name. */ credit_system_name: string; /** @description Name of one credit unit. */ unit_name: string; /** @description Status of the Credit System, for example `active`. */ system_status: string; /** @description Sum of `remaining` over sources whose `available` is `true`, as a decimal string. */ available: string; /** @description Credits reserved by open holds, as a decimal string (Engine 2.34.0+). */ held?: string; /** * Format: date-time * @description Time the balance was read; source validity is evaluated at this time. */ as_of: string; /** @description Active or scheduled sources, earliest `expires_at` first (no expiry last), then `priority`. */ sources: components["schemas"]["CreditsBalanceSource"][]; }; CreditsCustomerBalanceList: { customer_id: string; /** Format: date-time */ as_of: string; /** @description One item per Credit System, ordered by `credit_system` code. */ balances: components["schemas"]["CreditsCustomerBalance"][]; }; /** * @description An Entity's balance in one Credit System, with separate Entity, shared and effective views. * @example { * "customer_id": "workspace_123", * "entity_id": "user_42", * "entity_status": "active", * "credit_system": "ai_credits", * "credit_system_id": "c15f2949-7df6-4f05-89af-3f1b0bc82189", * "credit_system_name": "AI Credits", * "unit_name": "credit", * "system_status": "active", * "entity_available": "480.000000000001", * "shared_available": "250", * "effective_available": "730.000000000001", * "consumed": "42", * "pool_policy": "entity_then_customer", * "as_of": "2026-07-22T12:00:00.750Z", * "sources": [ * { * "id": "6f0c1d1e-8a55-4d0e-9d0b-2c1f7b0a9e11", * "entity_id": "user_42", * "parent_source_id": "3a2b9c4d-1e2f-4a5b-8c9d-0e1f2a3b4c5d", * "scope": "entity", * "transferable": false, * "returnable": true, * "type": "allocated_top_up", * "reference": "allocation:2f7e...", * "subscription_id": null, * "initial": "100", * "remaining": "100", * "valid_from": "2026-07-21T09:00:00Z", * "expires_at": null, * "priority": 100, * "status": "active", * "available": true * } * ] * } */ CreditsEntityBalance: { customer_id: string; /** @description External Entity ID. */ entity_id: string; /** @enum {string} */ entity_status: "active" | "suspended"; credit_system: string; credit_system_id: string; credit_system_name: string; unit_name: string; system_status: string; /** @description Available amount in Entity-owned sources. */ entity_available: string; /** @description Available amount in the shared customer pool. */ shared_available: string; /** @description Amount the Entity can spend under the current pool policy. `0` when the Entity is inactive or no unambiguous policy exists. */ effective_available: string; /** @description Amount consumed by this Entity. */ consumed: string; /** @description Credits reserved by open holds: the Entity's own, the shared pool's, and the pool the Entity spends from (Engine 2.34.0+). */ entity_held?: string; shared_held?: string; held?: string; /** * @description Pool policy of the active plan for this Credit System; `null` when none applies. * @enum {string|null} */ pool_policy: "entity_only" | "entity_then_customer" | "customer_only" | null; /** Format: date-time */ as_of: string; sources: components["schemas"]["CreditsBalanceSource"][]; }; CreditsEntityBalanceList: { customer_id: string; entity_id: string; /** @enum {string} */ entity_status: "active" | "suspended"; /** Format: date-time */ as_of: string; balances: components["schemas"]["CreditsEntityBalance"][]; }; CreditsOperationAllocation: { source_id: string; /** @description External Entity ID of the source, `null` for a customer-level source. */ source_entity_id: string | null; source_type: string; /** @description Signed change applied to the source. */ delta: string; /** @description Source remaining amount before the operation. */ before: string; /** @description Source remaining amount after the operation. */ after: string; }; /** * @description One immutable credit ledger operation. * @example { * "id": "8d3c2b1a-0f9e-4d8c-b7a6-5e4d3c2b1a09", * "entity_id": null, * "credit_system": "ai_credits", * "credit_system_id": "c15f2949-7df6-4f05-89af-3f1b0bc82189", * "credit_system_name": "AI Credits", * "unit_name": "credit", * "feature_code": "agent_execution", * "type": "consume", * "status": "succeeded", * "metric_amount": "1", * "credit_amount": "2", * "rate_id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b", * "rate_metric_amount": "1", * "rate_credit_amount": "2", * "reason": null, * "occurred_at": "2026-07-20T12:00:00.750Z", * "source_allocations": [ * { * "source_id": "bf659149-0d70-4d2a-8a7b-a4569cc742eb", * "source_entity_id": null, * "source_type": "subscription_grant", * "delta": "-2", * "before": "625.5", * "after": "623.5" * } * ] * } */ CreditsOperation: { id: string; /** @description External Entity ID the operation is attributed to, or `null`. */ entity_id: string | null; credit_system: string; credit_system_id: string; credit_system_name: string; unit_name: string; feature_code: string | null; /** @enum {string} */ type: "consume" | "grant" | "adjustment" | "expire" | "revoke" | "refund" | "transfer"; /** @enum {string} */ status: "succeeded" | "denied" | "reversed"; /** @description Metric amount snapshot as a decimal string. */ metric_amount: string | null; /** @description Credit amount of the operation. On a `revoke`, what was actually revoked. */ credit_amount: string; /** @description On a `revoke` operation, the credits that were asked to be taken back. `credit_amount` is what was actually revoked; the difference had already been spent. `null` for other operation types. */ requested_credit_amount?: string | null; rate_id: string | null; /** @description Rate snapshot: metric side, decimal string. */ rate_metric_amount: string | null; /** @description Rate snapshot: credit side, decimal string. */ rate_credit_amount: string | null; /** @description Reason code, for example on a denied consume. A `revoke` of a paid top-up's credits has `top_up_credit_note` (a credit note on the top-up invoice) or `top_up_dispute_lost` (a lost payment dispute). */ reason: string | null; /** Format: date-time */ occurred_at: string; /** @description Source-level changes. Empty for a denied consume. */ source_allocations: components["schemas"]["CreditsOperationAllocation"][]; }; CreditsCustomerOperationPage: { customer_id: string; operations: components["schemas"]["CreditsOperation"][]; /** @description Cursor for the next page; `null` when there are no more operations. */ next_cursor: string | null; }; CreditsEntityOperationPage: { customer_id: string; entity_id: string; operations: components["schemas"]["CreditsOperation"][]; /** @description Cursor for the next page; `null` when there are no more operations. */ next_cursor: string | null; }; /** * @example { * "id": "0e7c5a7e-3b8f-4c6a-9f1d-2a4b6c8d0e1f", * "customer_id": "workspace_123", * "external_id": "user_42", * "name": "Asha", * "status": "active", * "metadata": { * "role": "agent" * }, * "created_at": "2026-07-22T10:00:00Z", * "updated_at": "2026-07-22T10:00:00Z", * "deleted_at": null * } */ CreditsEntity: { /** @description Durable Entity UUID. An Entity keeps its id for its whole life; Entities cannot be deleted. */ id: string; /** @description External customer ID. */ customer_id: string; /** @description Your Entity ID. */ external_id: string; name: string | null; /** @enum {string} */ status: "active" | "suspended"; metadata: { [key: string]: unknown; }; /** Format: date-time */ created_at: string; /** Format: date-time */ updated_at: string; /** Format: date-time */ deleted_at: string | null; }; CreditsEntityEnvelope: { entity: components["schemas"]["CreditsEntity"]; }; CreditsEntityPage: { customer_id: string; entities: components["schemas"]["CreditsEntity"][]; /** @description Cursor for the next page; `null` at the end. */ next_cursor: string | null; }; /** @description Complete snapshot of the Entity. Unknown fields are rejected. Fields left out are cleared, so send the current `name` and `metadata` when you change only `status`. */ CreditsEntityUpsertRequest: { /** @description Display name, at most 255 characters after trimming. An empty or missing value stores no name. */ name?: string | null; /** * @description Required: `active` or `suspended`. Any other value, including `deleted`, returns `400 invalid_request`. Entities cannot be deleted. Suspending an Entity does not cancel its subscription: cancel the Entity subscription yourself to stop billing. A legacy Entity already in `deleted` status is never revived: changing its status returns `422 entity_status_transition_invalid`. * @enum {string} */ status: "active" | "suspended"; /** @description JSON object, at most 65536 bytes when encoded. Omitted means `{}`. */ metadata?: { [key: string]: unknown; }; }; CreditsEntityBulkItem: { /** @description Entity ID, 1 to 255 bytes after trimming. Must be unique within the request. */ external_id: string; /** @description Display name, at most 255 characters after trimming. An empty or missing value stores no name. */ name?: string | null; /** * @description Required: `active` or `suspended`. Any other value, including `deleted`, returns `400 invalid_request`. Entities cannot be deleted. Suspending an Entity does not cancel its subscription: cancel the Entity subscription yourself to stop billing. A legacy Entity already in `deleted` status is never revived: changing its status returns `422 entity_status_transition_invalid`. * @enum {string} */ status: "active" | "suspended"; /** @description JSON object, at most 65536 bytes when encoded. Omitted means `{}`. */ metadata?: { [key: string]: unknown; }; }; CreditsEntityBulkUpsertRequest: { entities: components["schemas"]["CreditsEntityBulkItem"][]; }; CreditsEntityMutationItem: { /** @enum {string} */ action: "created" | "updated" | "unchanged" | "activated" | "suspended"; entity: components["schemas"]["CreditsEntity"]; }; /** * @example { * "action": "created", * "entity": { * "id": "0e7c5a7e-3b8f-4c6a-9f1d-2a4b6c8d0e1f", * "customer_id": "workspace_123", * "external_id": "user_42", * "name": "Asha", * "status": "active", * "metadata": { * "role": "agent" * }, * "created_at": "2026-07-22T10:00:00Z", * "updated_at": "2026-07-22T10:00:00Z", * "deleted_at": null * }, * "replayed": false * } */ CreditsEntityMutationResult: { /** @enum {string} */ action: "created" | "updated" | "unchanged" | "activated" | "suspended"; entity: components["schemas"]["CreditsEntity"]; /** @description `true` when this is the stored result of an earlier request with the same idempotency key. */ replayed: boolean; }; CreditsEntityBulkMutationCounts: { created: number; updated: number; unchanged: number; activated: number; /** @description Always `0`; Entities are no longer reactivated or deleted. */ reactivated: number; suspended: number; /** @description Always `0`; Entities cannot be deleted. */ deleted: number; }; CreditsEntityBulkMutationResult: { customer_id: string; entities: components["schemas"]["CreditsEntityMutationItem"][]; counts: components["schemas"]["CreditsEntityBulkMutationCounts"]; replayed: boolean; }; CreditsTransferRequest: { /** @description Credit System code. */ credit_system: string; /** * @description Positive decimal string with at most 18 integer digits and 12 fractional digits. * @example 100.000000000001 */ amount: string; }; CreditsTransferSource: { source_id: string; /** @description Parent customer source of an allocated source. Omitted when not set. */ parent_source_id?: string; /** @enum {string} */ source_type: "top_up" | "allocated_top_up"; /** @enum {string} */ scope: "customer" | "entity"; /** @description Amount moved through this source; always positive. */ amount: string; /** @description Source remaining amount before the transfer. */ before: string; /** @description Source remaining amount after the transfer. */ after: string; /** Format: date-time */ expires_at: string | null; /** @description `true` when the transfer created this source. Omitted when `false`. */ created?: boolean; }; CreditsTransferResult: { /** @description `false` when there was not enough eligible value; the response status is then `422`. */ transferred: boolean; operation_id: string; customer_id: string; entity_id: string; credit_system: string; /** @enum {string} */ direction: "allocation" | "deallocation"; /** @description Requested amount. */ amount: string; /** @description Eligible value available for this direction. */ available: string; /** * @description Set when `transferred` is `false`; omitted otherwise. * @enum {string} */ reason?: "insufficient_customer_top_up_credits" | "insufficient_entity_allocated_credits"; /** @description Customer-level paid top-up sources involved. */ parent_sources: components["schemas"]["CreditsTransferSource"][] | null; /** @description Entity-level allocated sources involved. */ entity_sources: components["schemas"]["CreditsTransferSource"][] | null; replayed: boolean; }; CreditsBalanceImportRequest: { /** @description Entity ID for an Entity-scoped balance. Omit for a customer balance. */ external_entity_id?: string; /** @description Subscription ID returned by the Core billing-state import. */ external_subscription_id: string; credit_system_code: string; /** @description Positive decimal string. Must equal Nozle's computed grant for the current period, or the request returns `422 grant_amount_mismatch`. */ granted_amount: string; /** @description Decimal string from zero up to `granted_amount`. */ remaining_amount: string; /** * @description `true` validates without writing ledger state. * @default false */ dry_run: boolean; }; CreditsBalanceImport: { /** @description Omitted when empty (for example on a dry run). */ operation_id?: string; /** @description Omitted when empty (for example on a dry run). */ balance_source_id?: string; external_customer_id: string; /** @description Omitted for a customer balance. */ external_entity_id?: string; external_subscription_id: string; credit_system_code: string; granted_amount: string; remaining_amount: string; /** Format: date-time */ current_period_start: string; /** * Format: date-time * @description Omitted when the source does not expire. */ expires_at?: string; /** @description Always `false`; the import never creates an invoice. */ invoice_created: boolean; dry_run: boolean; replayed: boolean; }; /** * @example { * "credit_balance_import": { * "operation_id": "operation_uuid", * "balance_source_id": "source_uuid", * "external_customer_id": "workspace_123", * "external_subscription_id": "merchant_subscription_123", * "credit_system_code": "ai_credits", * "granted_amount": "500", * "remaining_amount": "320", * "current_period_start": "2026-08-15T00:00:00Z", * "expires_at": "2026-09-15T00:00:00Z", * "invoice_created": false, * "dry_run": false, * "replayed": false * } * } */ CreditsBalanceImportResponse: { credit_balance_import: components["schemas"]["CreditsBalanceImport"]; }; CreditsTopUpPurchaseRequest: { /** @description External customer ID. Required with a secret key. With trusted internal authentication it defaults to the `X-Nozle-Customer-Id` header. */ customer_id?: string; /** @description Credit System code (Core also accepts its ID). */ credit_system_code: string; /** @description Top-up package code (Core also accepts its ID). */ top_up_package_code: string; }; /** @description Purchase snapshot serialized by Nozle Core and passed through unchanged by the Engine. */ CreditsTopUpPurchase: { nozle_id?: string; organization_id?: string; customer_id?: string; external_customer_id?: string; credit_system_id?: string; credit_system_code?: string; top_up_package_id?: string; package_code?: string; package_name?: string | null; /** @description Credits the package grants, as a decimal string. */ credit_amount?: string; amount_cents?: number; currency?: string; expires_after_days?: number | null; invoice_id?: string; invoice_number?: string | null; invoice_amount_cents?: number; /** * @description Payment of the top-up invoice. `succeeded` does not mean the credits can be spent yet; see `fulfillment_status`. * @enum {string} */ payment_status?: "pending" | "succeeded" | "failed" | "voided"; /** * @description `fulfilled` once the credits are granted and can be spent (Core 11.1.0 and later), then the `credit_top_up_purchase.fulfilled` webhook is sent. `pending` before. * @enum {string} */ fulfillment_status?: "pending" | "fulfilled"; /** * Format: date-time * @description When the credits were granted, or `null` while `fulfillment_status` is `pending`. */ fulfilled_at?: string | null; payment_id?: string | null; /** @description For example `stripe` or `razorpay`. */ payment_provider?: string | null; payment_provider_type?: string | null; payment_provider_code?: string | null; provider_payment_id?: string | null; /** @description Hosted payment page. Stripe: a `checkout.stripe.com` page (checkout results carry it as `url` too). Razorpay: an `rzp.io` payment link. */ payment_url?: string | null; replayed?: boolean; /** Format: date-time */ created_at?: string; }; CreditsTopUpPurchaseResponse: { credit_top_up_purchase: components["schemas"]["CreditsTopUpPurchase"]; }; /** * @example { * "wallet_id": "09b4f6d3-f463-4f4f-ac75-27e36bc2a296", * "name": "Prepaid wallet", * "balance_cents": 1600, * "currency": "USD", * "credits_balance": "16.00000", * "status": "active" * } */ CreditsLegacyWalletBalance: { wallet_id: string; /** @description Empty string when the wallet has none. */ name: string; /** * Format: int64 * @description Money balance in the smallest unit of the currency. `POST /check-and-deduct` lowers it with the credits it deducts. */ balance_cents: number; currency: string; /** @description Credits left, as the database decimal text (for example `16.00000`). Live value; every check-and-deduct changes it. */ credits_balance: string; /** * @description Only active wallets are returned. * @enum {string} */ status: "active"; }; CreditsLegacyWalletTransaction: { id: string; /** @enum {string} */ type: "inbound" | "outbound" | "unknown"; /** @enum {string} */ status: "pending" | "settled" | "unknown"; /** @description Money amount in the wallet currency, as decimal text. For a check-and-deduct transaction it is the credits × the wallet rate. */ amount: string; /** @description Credits, as decimal text. */ credit_amount: string; /** @description UTC time formatted `YYYY-MM-DDTHH:MM:SSZ`, or `null`. */ settled_at: string | null; /** @description UTC time formatted `YYYY-MM-DDTHH:MM:SSZ`. */ created_at: string; }; CreditsLegacyWalletTransactionList: { transactions: components["schemas"]["CreditsLegacyWalletTransaction"][]; }; /** * @description Unix seconds (a positive JSON number such as `1788345001` or `1788345001.5`, or a numeric string such as `"1788345001"`) or an RFC 3339 string with an offset or `Z`. RFC 3339 keeps nanoseconds and offset. * @example 2026-07-20T12:00:00.750Z */ CreditsEventTime: number | string; /** @description Unknown fields are rejected. The body must be one JSON object of at most 1 MiB. */ CreditsUsageCheckRequest: { /** @description External customer ID (trimmed). */ customer_id: string; /** @description External Entity ID to attribute and pool the usage. Omit for customer-level usage. */ entity_id?: string; /** @description External ID of the active subscription of the customer that pays for the usage. Optional. Without it, with `entity_id` the Entity's own active subscription pays, else the customer's own (not Entity-owned) one; without either, the customer's one active subscription pays. With `entity_id`, it must not be another Entity's subscription. An unknown or inactive subscription returns `404 active_subscription_not_found`. */ subscription_id?: string; /** @description Code of a consumable Feature. */ feature_code: string; /** @description Credit System to use. Omit when only one effective rate applies; two or more give `422 credit_usage_configuration_invalid`. */ credit_system_code?: string; /** @description Event properties used to derive the metric amount. Omitted means `{}`. */ properties?: { [key: string]: unknown; }; /** @description Required. Time the usage occurs. A missing, null or blank value returns `400 invalid_request` (`occurred_at is required`). */ occurred_at: components["schemas"]["CreditsEventTime"]; }; /** @description Unknown fields are rejected. The body must be one JSON object of at most 1 MiB. */ CreditsUsageTrackRequest: { /** @description External customer ID (trimmed). */ customer_id: string; /** @description External Entity ID to attribute and pool the usage. Omit for customer-level usage. */ entity_id?: string; /** @description External ID of the active subscription of the customer that pays for the usage. Optional. Without it, with `entity_id` the Entity's own active subscription pays, else the customer's own (not Entity-owned) one; without either, the customer's one active subscription pays. With `entity_id`, it must not be another Entity's subscription. An unknown or inactive subscription returns `404 active_subscription_not_found`. */ subscription_id?: string; /** @description Code of a consumable Feature. */ feature_code: string; /** @description Credit System to use. Omit when only one effective rate applies; two or more give `422 credit_usage_configuration_invalid`. */ credit_system_code?: string; /** @description Event properties used to derive the metric amount. Omitted means `{}`. */ properties?: { [key: string]: unknown; }; /** @description Required; the API does not default it. A missing, null or blank value returns `400 invalid_request` (`timestamp is required`). Send the same value on every retry; the same instant in another form is a different body. */ timestamp: components["schemas"]["CreditsEventTime"]; }; CreditsUsageDeduction: { /** @description Omitted when empty. */ balance_source_id?: string; source_type: string; /** @enum {string} */ source_scope: "entity" | "customer"; /** @description Credits taken from the source. */ amount: string; /** @description Source remaining amount after the deduction. */ remaining: string; }; /** * @description Advisory decision. No source or ledger row changes. Empty string fields are omitted. * @example { * "advisory": true, * "allowed": true, * "metric_amount": "1", * "credit_system": "ai_credits", * "credits_required": "2", * "available": "625", * "projected_remaining": "623", * "projected_deductions": [ * { * "balance_source_id": "0f89c1d2-...", * "source_type": "subscription_grant", * "source_scope": "customer", * "amount": "2", * "remaining": "373" * } * ] * } */ CreditsUsageCheckResponse: { /** @constant */ advisory: true; allowed: boolean; entity_id?: string; /** @enum {string} */ pool_policy?: "entity_only" | "entity_then_customer" | "customer_only"; /** @description Metric amount derived from `properties`. */ metric_amount: string; credit_system: string; /** @description Credits the usage would cost. */ credits_required: string; /** @description Spendable credits now. */ available: string; /** @description Remaining credits after the projected deduction. Only when `allowed` is `true`. */ projected_remaining?: string; /** @description Reason code when `allowed` is `false`, for example `insufficient_credits`. */ reason?: string; /** @description Projected source selection, in consume order. Only when `allowed` is `true` and not empty. */ projected_deductions?: components["schemas"]["CreditsUsageDeduction"][]; /** @description The used-up hard spend limit, with `reason` `budget_exceeded` (Engine 2.34.0+). */ budget?: components["schemas"]["Budget"]; }; /** * @description Result of an authoritative consume. When `allowed` is `true` the body has `operation_id`, `metric_amount`, `credit_system`, `credits_consumed`, `remaining` and `deductions`. When `false` it has `credits_required`, `available` and `reason`, and nothing was consumed. Empty fields are omitted. * @example { * "allowed": true, * "operation_id": "8d3c2b1a-0f9e-4d8c-b7a6-5e4d3c2b1a09", * "metric_amount": "1", * "credit_system": "ai_credits", * "credits_consumed": "2", * "remaining": "623", * "deductions": [ * { * "balance_source_id": "bf659149-0d70-4d2a-8a7b-a4569cc742eb", * "source_type": "subscription_grant", * "source_scope": "customer", * "amount": "2", * "remaining": "623.5" * } * ] * } */ CreditsUsageTrackResponse: { allowed: boolean; operation_id?: string; entity_id?: string; /** @enum {string} */ pool_policy?: "entity_only" | "entity_then_customer" | "customer_only"; /** @description Metric amount derived from `properties`. */ metric_amount?: string; credit_system?: string; /** @description Credits consumed. */ credits_consumed?: string; /** @description Spendable credits after the consume. */ remaining?: string; /** @description Credits the usage needed (denied result). */ credits_required?: string; /** @description Spendable credits (denied result). */ available?: string; /** @description Reason code of a denial, for example `insufficient_credits`. */ reason?: string; deductions?: components["schemas"]["CreditsUsageDeduction"][]; /** @description The used-up hard spend limit, with `reason` `budget_exceeded` (Engine 2.34.0+). */ budget?: components["schemas"]["Budget"]; }; /** @description Unknown fields, including the old `feature` field, are ignored. */ CreditsCheckAndDeductRequest: { /** @description External customer ID. */ customer_id: string; /** @description Credits to deduct, as a JSON number. */ credits: number; }; /** * @example { * "allowed": true, * "remaining": 95 * } */ CreditsCheckAndDeductResponse: { /** @description Whether the wallet had enough credits. */ allowed: boolean; /** @description Wallet `credits_balance` after the deduction, as a JSON number (float). Unchanged when `allowed` is `false`. */ remaining: number; }; /** @description Error body written when the date range cannot be parsed or is empty. */ MarginDateRangeError: { /** @constant */ code: "invalid_date_range"; /** @description What failed, for example the parameter that could not be parsed. */ error: string; }; MarginSummary: { /** * Format: int64 * @description Total revenue in integer cents. */ total_revenue_cents: number; /** * Format: int64 * @description Total cost in integer cents. */ total_cost_cents: number; /** * Format: int64 * @description Total margin in integer cents; can be negative. */ total_margin_cents: number; /** * Format: double * @description total_margin_cents / total_revenue_cents * 100; 0 when total revenue is not positive. Not rounded. */ margin_percent: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; MarginCustomerRow: { /** @description Customer ID recorded on the margin events. */ customer_id: string; /** @description Customer name from the Engine customer cache: name, else external ID, else ID. Equals `customer_id` when the customer is not in the cache. */ customer_name: string; /** * Format: int64 * @description Revenue in integer cents. */ revenue_cents: number; /** * Format: int64 * @description Cost in integer cents. */ cost_cents: number; /** * Format: int64 * @description Revenue minus cost in integer cents; can be negative. */ margin_cents: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; MarginMetricRow: { /** @description Metric code recorded on the margin events. */ metric_code: string; /** * Format: int64 * @description Revenue in integer cents. */ revenue_cents: number; /** * Format: int64 * @description Cost in integer cents. */ cost_cents: number; /** * Format: int64 * @description Revenue minus cost in integer cents; can be negative. */ margin_cents: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; MarginPlanRow: { /** @description Plan ID recorded on the margin events; empty for events without a plan. */ plan_id: string; /** * Format: int64 * @description Revenue in integer cents. */ revenue_cents: number; /** * Format: int64 * @description Cost in integer cents. */ cost_cents: number; /** * Format: int64 * @description Revenue minus cost in integer cents; can be negative. */ margin_cents: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; MarginModelRow: { /** @description Value of the event's `model` property. */ model: string; /** * Format: int64 * @description Revenue in integer cents. */ revenue_cents: number; /** * Format: int64 * @description Cost in integer cents. */ cost_cents: number; /** * Format: int64 * @description Revenue minus cost in integer cents; can be negative. */ margin_cents: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; MarginByCustomerResponse: { /** @description Rows ordered by margin_cents ascending; null when there are none. */ customers: components["schemas"]["MarginCustomerRow"][] | null; }; MarginByMetricResponse: { /** @description Rows ordered by margin_cents ascending; null when there are none. */ metrics: components["schemas"]["MarginMetricRow"][] | null; }; MarginByPlanResponse: { /** @description Rows ordered by margin_cents ascending; null when there are none. */ plans: components["schemas"]["MarginPlanRow"][] | null; }; MarginByModelResponse: { /** @description Rows ordered by cost_cents descending; null when there are none. */ models: components["schemas"]["MarginModelRow"][] | null; }; MarginTrendPoint: { /** @description Start of the bucket as ClickHouse prints it: `YYYY-MM-DD HH:MM:SS` for hour and day buckets (and any unrecognised granularity), `YYYY-MM-DD` for week and month buckets. */ period: string; /** * Format: int64 * @description Revenue in integer cents. */ revenue_cents: number; /** * Format: int64 * @description Cost in integer cents. */ cost_cents: number; /** * Format: int64 * @description Margin in integer cents; can be negative. */ margin_cents: number; /** * Format: double * @description margin_cents / revenue_cents * 100; 0 when revenue is not positive. */ margin_percent: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; MarginTrendResponse: { /** @description The granularity query value as sent (or `day` when missing or empty). Not validated, so it can be a value that was bucketed by day. */ granularity: string; /** @description Buckets ordered by period ascending; null when the range has no events. */ trend: components["schemas"]["MarginTrendPoint"][] | null; }; MarginForecastPoint: { /** * Format: date * @description Projected day (UTC). */ date: string; /** * Format: int64 * @description Projected revenue in integer cents (the name has no _cents suffix); never negative. */ projected_revenue: number; /** * Format: int64 * @description Projected cost in integer cents; never negative. */ projected_cost: number; /** * Format: int64 * @description projected_revenue minus projected_cost, in integer cents; can be negative. */ projected_margin: number; }; MarginForecastResponse: { /** @description 30 points, or an empty array when fewer than 2 day buckets exist. Never null. */ points: components["schemas"]["MarginForecastPoint"][]; /** * @description low below 7 day buckets, medium for 7 to 19, high for 20 or more. * @enum {string} */ confidence: "low" | "medium" | "high"; }; /** @description An unknown field returns 400 `invalid_request`. */ MarginSimulateRequest: { /** * @description Code of the metric to simulate. Missing or empty returns 400 `invalid_request` with `metric_code required`. * @example agent_execution */ metric_code: string; /** * Format: double * @description New price per unit of usage, in dollars, as a JSON number of 0 or more. A missing, negative or string value returns 400 `invalid_request`. * @example 1 */ new_price_dollars: number; }; MarginSimulationResult: { /** @description The metric_code from the request. */ metric_code: string; /** * Format: int64 * @description Recorded revenue in the range. */ current_revenue_cents: number; /** * Format: int64 * @description Recorded cost in the range. */ current_cost_cents: number; /** * Format: int64 * @description current_revenue_cents minus current_cost_cents. */ current_margin_cents: number; /** * Format: int64 * @description Total recorded quantity x new_price_dollars x 100, truncated toward zero. */ new_revenue_cents: number; /** * Format: int64 * @description Always equal to current_cost_cents. */ new_cost_cents: number; /** * Format: int64 * @description new_revenue_cents minus new_cost_cents. */ new_margin_cents: number; /** * Format: int64 * @description new_revenue_cents minus current_revenue_cents. */ revenue_delta_cents: number; /** * Format: int64 * @description new_margin_cents minus current_margin_cents. */ margin_delta_cents: number; /** * Format: int64 * @description Number of margin events aggregated (unsigned 64-bit in the Engine). */ event_count: number; }; /** @description Entitlement decision returned by `GET /can`. */ PlatformCanResponse: { /** @description Whether the customer may use the feature now. */ allowed: boolean; /** * @description Denial code. Present only when `allowed` is `false`. `customer_payment_overdue` (Engine 2.22.0) comes with HTTP `402`, every other reason with `200`. * @enum {string} */ reason?: "feature_not_found" | "no_subscription" | "subscription_required" | "no_entitlement" | "usage_limit_exceeded" | "economic_policy_denied" | "customer_payment_overdue" | "budget_exceeded"; /** @description Feature type, such as `boolean`, `config` or `metered`. Absent when the feature or subscription is missing, and when a metered feature has neither an entitlement nor a charge. */ feature_type?: string; /** @description Configuration values granted by the plan for a non-metered feature. Absent when there are none. */ configuration?: { [key: string]: string; }; /** * Format: int64 * @description Units used in the current billing period (the running total for a recurring feature), as a whole number (fractional usage is truncated). Also the real usage of a metered feature priced only by a charge. `0` for non-metered features and for denials decided before usage is read. */ used: number; /** * Format: int64 * @description Usage limit from the entitlement. `null` when there is no cap, the feature is not metered, or a metered feature has no entitlement. */ limit: number | null; /** * Format: int64 * @description `limit` minus `used`, never below 0. `null` when `limit` is `null`. */ remaining: number | null; /** @description `true` when usage reached a soft limit; the request is still allowed. Absent otherwise. */ overage?: boolean; economics?: components["schemas"]["PlatformCanEconomics"]; policy?: components["schemas"]["PlatformCanPolicy"]; /** @description The spend limit that refused the call (`budget_exceeded`), else the tightest one covering the Feature (Engine 2.34.0+). */ budget?: components["schemas"]["Budget"]; }; /** @description One money budget (spend limit) and its standing in the current period. Amounts are decimal strings in major units of `currency` (Engine 2.34.0+). */ Budget: { /** @description The Feature the limit covers; `null` for the subscription's total limit. */ feature_code: string | null; limit: string; spent: string; held: string; remaining: string; currency: string; /** @enum {string} */ period: "billing_period" | "calendar_month" | "lifetime"; /** Format: date-time */ period_start: string; /** @description `null` for a `lifetime` limit. */ period_end: string | null; /** @enum {string} */ mode: "hard" | "soft"; /** @enum {string} */ status: "ok" | "warning" | "exceeded"; /** @description Time of the latest event booked into `spent`. */ as_of: string | null; /** * Format: date-time * @description Engine 2.38.0. When `spent` starts: `period_start` once the period's spend is counted in full; before that (a limit added mid-period, for about 5 minutes), the time counting started; `null` when nothing is counted yet. */ counted_from: string | null; }; /** @description Point-in-time estimate for the proposed call of an allowed metered feature. Monetary values are exact decimal strings in `currency`, not cents. */ PlatformCanEconomics: { /** @enum {string} */ status: "estimated" | "not_configured" | "unavailable" | "stale"; /** @description ISO 4217 reporting currency of the estimate. */ currency?: string; /** @description Present when `status` is `estimated`. */ estimated_incremental_cost?: string; /** @description Revenue of the proposed call: the standard charge's unit price × the call's units, `0` when there is no charge. A count feature adds 1 unit; a sum feature adds the value of its `field_name` in `metadata`. Without that value, and for max, latest, unique count, weighted sum and custom aggregations, `status` is `unavailable` and `excludes` has `revenue_quantity_missing` or `non_additive_revenue_aggregation`. */ estimated_incremental_revenue?: string; /** @description Revenue minus cost. Present when the cost is estimated. */ estimated_incremental_margin?: string; /** @description Margin as a percentage of revenue, rounded to 8 decimal places. Absent when revenue is not positive. */ estimated_margin_percent?: string; /** @description Cost Sheet rule versions used. */ rule_version_ids?: string[]; /** @description What was calculated, such as `feature_event_cost`. */ includes?: string[]; /** @description Costs that are not in the estimate, such as `shared_period_costs`, `finalized_invoice_adjustments`, `non_standard_revenue_pricing`, `revenue_quantity_missing`, `non_additive_revenue_aggregation` or `foreign_exchange_conversion`. */ excludes?: string[]; /** @description Machine code explaining a status other than `estimated`, such as `cost_estimator_unavailable`, `cost_estimate_failed`, `no_matching_cost_rule`, `estimated_revenue_unavailable`, `revenue_currency_mismatch` or `snapshot_too_old`. */ reason?: string; /** * Format: date-time * @description RFC 3339 time of the estimate, with nanoseconds. */ calculated_at: string; }; /** @description Margin policy that applied to the decision. */ PlatformCanPolicy: { /** @description Margin policy version ID. */ version_id: string; /** * @description Decision used when a threshold is broken. `deny` denies the request. * @enum {string} */ mode: "allow" | "warn" | "deny"; /** * @description Decision used when economics are not `estimated` (for example `unavailable` because the call's revenue cannot be estimated) or cannot be compared. * @enum {string} */ on_unavailable: "allow" | "warn" | "deny"; /** * @description What the policy does for a feature with no Cost Rule. Engine 2.39.0; absent on older Engines. * @enum {string} */ on_not_configured?: "allow" | "warn" | "deny"; /** * @description The target of the policy that decided the call. Engine 2.40.0; absent on older Engines. * @enum {string} */ scope?: "customer" | "plan" | "feature" | "organization"; /** @description Decimal string. Absent when not set. */ minimum_margin_amount?: string; /** @description Decimal string. Absent when not set. */ minimum_margin_percent?: string; /** @description Decimal string. Absent when not set. */ maximum_estimated_cost?: string; /** @description Oldest estimate the policy accepts; `0` means no limit. */ maximum_snapshot_age_seconds: number; /** * @description `allow`, or the policy's `mode` or `on_unavailable` value. `deny` sets `allowed` to `false` with reason `economic_policy_denied`. * @enum {string} */ decision: "allow" | "warn" | "deny"; /** @description Machine code such as `within_policy`, `maximum_estimated_cost_exceeded`, `minimum_margin_amount_not_met`, `minimum_margin_percentage_not_met`, `reporting_currency_mismatch` or `economics_`. */ reason: string; }; PlatformPingResponse: { /** @description `true` when the Engine database answered within 3 seconds. */ ok: boolean; /** @enum {string} */ engine: "ok" | "error"; }; /** @description A request or response body of the LLM provider, passed through unchanged. Its shape is defined by the provider. */ PlatformProviderPayload: { [key: string]: unknown; }; /** @description Per-model rate. */ PlatformCostModelRate: { /** * Format: int64 * @description Input rate in cents. */ input?: number; /** * Format: int64 * @description Output rate in cents. */ output?: number; }; PlatformCostModelTier: { /** * Format: int64 * @description Upper bound of the tier. `null` only on the last tier. */ up_to?: number | null; /** Format: int64 */ unit_amount_cents?: number; /** Format: int64 */ flat_amount_cents?: number; }; PlatformCostModelInput: { /** @description Non-blank name. */ name: string; /** @description Non-blank feature (metric) code the cost applies to. */ metric_code: string; /** @enum {string} */ cost_type: "per_unit" | "per_model" | "tiered"; /** * Format: int64 * @description Cost per unit in cents. Required for `per_unit`. */ amount_cents?: number; /** @description Rates keyed by model name. Required for `per_model`. */ model_rates?: { [key: string]: components["schemas"]["PlatformCostModelRate"]; }; /** * @description Required for `tiered`. * @enum {string} */ tier_mode?: "SLAB"; /** @description Required for `tiered`. */ tiers?: components["schemas"]["PlatformCostModelTier"][]; /** @description Event property filters; each key maps to the values it matches. */ filter_values?: { [key: string]: string[]; }; /** * @default active * @enum {string} */ status: "active" | "archived"; }; PlatformCostModel: { /** Format: uuid */ id: string; /** Format: uuid */ org_id: string; name: string; metric_code: string; /** @enum {string} */ cost_type: "per_unit" | "per_model" | "tiered"; /** * @description Absent when not set. * @enum {string} */ tier_mode?: "SLAB"; /** * Format: int64 * @description Absent when not set. */ amount_cents?: number; /** @description Absent when empty. */ model_rates?: { [key: string]: components["schemas"]["PlatformCostModelRate"]; }; /** @description Absent when empty. */ tiers?: components["schemas"]["PlatformCostModelTier"][]; /** @description Absent when empty. */ filter_values?: { [key: string]: string[]; }; /** @enum {string} */ status: "active" | "archived"; /** Format: date-time */ created_at: string; /** Format: date-time */ updated_at: string; }; PlatformCostModelList: { /** @description Cost models, newest first. `null` when the organization has none and paging is off. */ cost_models: components["schemas"]["PlatformCostModel"][] | null; /** @description Number of items in `cost_models`. */ count: number; meta?: components["schemas"]["PlatformCostModelPageMeta"]; }; /** @description Present only when `page` or `per_page` was sent. */ PlatformCostModelPageMeta: { current_page: number; limit_value: number; total_count: number; total_pages: number; }; PlatformCostModelArchived: { /** @enum {string} */ status: "archived"; }; QuoteVersionWebhookObject: { /** * Format: uuid * @description Unique identifier of the quote version. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * Format: uuid * @description Unique identifier of the quote. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ quote_id: string; /** * Format: uuid * @description Unique identifier of the organization. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** @description Version number, starting at 1. */ version: number; /** * @description Status of the quote version. * @enum {string} */ status: "draft" | "approved" | "voided"; /** * @description Three-letter ISO 4217 currency code. * @example USD */ currency?: string; /** @description Code of the billing entity. */ billing_entity_code?: string; /** * @description Why the version was voided. * @enum {string|null} */ void_reason?: "manual" | "superseded" | "cascade_of_expired" | "cascade_of_voided" | null; /** * Format: date-time * @description When the version was approved. * @example 2026-10-22T07:10:02Z */ approved_at?: string | null; /** * Format: date-time * @description When the version was voided. * @example 2026-10-22T07:10:02Z */ voided_at?: string | null; /** * Format: date-time * @description When the version was created. * @example 2026-10-22T07:10:02Z */ created_at: string; /** * Format: date-time * @description When the version was last updated. * @example 2026-10-22T07:10:02Z */ updated_at: string; }; /** @description A quote with the version the event happened to (not the quote's current version). */ QuoteWebhookObject: { /** * Format: uuid * @description Unique identifier of the quote. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Quote number. * @example QT-2026-0002 */ number: string; /** * @description What the quote orders. * @enum {string} */ order_type: "subscription_creation" | "subscription_amendment" | "one_off"; /** * Format: uuid * @description Unique identifier of the customer. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * Format: uuid * @description Unique identifier of the subscription an amendment quote changes. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id?: string | null; /** * Format: uuid * @description Unique identifier of the organization. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * Format: date-time * @description When the quote was created. * @example 2026-10-22T07:10:02Z */ created_at: string; /** * Format: date-time * @description When the quote was last updated. * @example 2026-10-22T07:10:02Z */ updated_at: string; version: components["schemas"]["QuoteVersionWebhookObject"]; }; OrderFormWebhookObject: { /** * Format: uuid * @description Unique identifier of the order form. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Order form number. * @example OF-2026-0001 */ number: string; /** * @description Status of the order form. * @enum {string} */ status: "generated" | "signed" | "expired" | "voided"; /** * @description Why the order form was voided. * @enum {string|null} */ void_reason?: "manual" | "expired" | "invalid" | null; /** * Format: date-time * @description When the order form expires. * @example 2026-10-22T07:10:02Z */ expires_at?: string | null; /** * Format: date-time * @description When the order form was signed. * @example 2026-10-22T07:10:02Z */ signed_at?: string | null; /** * Format: date-time * @description When the order form was voided. * @example 2026-10-22T07:10:02Z */ voided_at?: string | null; /** * Format: uri * @description URL of the signed document, when one was uploaded. */ signed_document_url?: string | null; /** * Format: uuid * @description Unique identifier of the organization. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * Format: uuid * @description Unique identifier of the customer. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * Format: uuid * @description Unique identifier of the quote. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ quote_id: string; /** * Format: uuid * @description Unique identifier of the approved quote version. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ quote_version_id: string; /** * Format: date-time * @description When the order form was created. * @example 2026-10-22T07:10:02Z */ created_at: string; /** * Format: date-time * @description When the order form was last updated. * @example 2026-10-22T07:10:02Z */ updated_at: string; }; OrderWebhookObject: { /** * Format: uuid * @description Unique identifier of the order. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Order number. * @example OR-2026-0001 */ number: string; /** * @description Status of the order. * @enum {string} */ status: "created" | "executed" | "failed"; /** * @description What the order does. * @enum {string} */ order_type: "subscription_creation" | "subscription_amendment" | "one_off"; /** * @description Whether Nozle creates the records or only records the order. * @enum {string|null} */ execution_mode?: "execute_in_nozle" | "order_only" | null; /** * @description Three-letter ISO 4217 currency code. * @example USD */ currency?: string; /** * Format: date-time * @description When the order was executed. * @example 2026-10-22T07:10:02Z */ executed_at?: string | null; /** @description What the execution created. It has the same keys on every order. */ execution_record: { /** @description When the order was executed. */ executed_at?: string | null; /** @description Execution mode recorded with the execution. */ execution_mode?: string | null; /** * Format: uuid * @description Invoice created by the execution. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ invoice_id?: string | null; /** @description Subscriptions created. */ subscription_ids?: string[]; /** @description Subscriptions terminated. */ terminated_subscription_ids?: string[]; /** @description Coupons applied. */ applied_coupon_ids?: string[]; /** @description Wallets created. */ wallet_ids?: string[]; /** @description Error codes of a failed execution, for example `customer_not_found`. */ errors?: string[]; }; /** * Format: uuid * @description Unique identifier of the organization. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ organization_id: string; /** * Format: uuid * @description Unique identifier of the customer. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * Format: uuid * @description Unique identifier of the signed order form. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ order_form_id: string; /** * Format: date-time * @description When the order was created. * @example 2026-10-22T07:10:02Z */ created_at: string; /** * Format: date-time * @description When the order was last updated. * @example 2026-10-22T07:10:02Z */ updated_at: string; }; PaymentReceiptWebhookObject: { /** * Format: uuid * @description Unique identifier of the payment receipt. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Receipt number. * @example PUL-CDDE-380-RCPT-000001 */ number: string; /** * Format: uri * @description URL of the receipt PDF. `null` until the PDF is generated. */ file_url?: string | null; /** * Format: uri * @description URL of the receipt XML. */ xml_url?: string | null; payment: components["schemas"]["PaymentObject"]; /** * Format: date-time * @description When the receipt was created. * @example 2026-10-22T07:10:02Z */ created_at: string; }; PlanUpgradeIntentWebhookObject: { /** * Format: uuid * @description Unique identifier of the plan upgrade intent. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ nozle_id: string; /** * @description Status of the intent. It is `needs_review` in this event. * @enum {string} */ status: "pending" | "processing" | "payment_failed" | "applied" | "canceled" | "expired" | "needs_review"; /** @description Why the change could not be applied, for example `plan_upgrade_apply_failed`. */ error_code?: string | null; /** * Format: uuid * @description Unique identifier of the customer. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ customer_id: string; /** * Format: uuid * @description Subscription being changed. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ subscription_id?: string | null; /** * Format: uuid * @description Plan the customer paid to move to. * @example 1a901a90-1a90-1a90-1a90-1a901a901a90 */ target_plan_id: string; /** * @description Amount of the payment, in cents. * @example 919 */ amount_cents: number; /** * @description Three-letter ISO 4217 currency code. * @example USD */ currency: string; /** @description Payment ID at the provider. The payment is refunded. */ provider_payment_id?: string | null; /** * Format: date-time * @description When the intent was created. * @example 2026-10-22T07:10:02Z */ created_at: string; /** * Format: date-time * @description When the intent was last updated. * @example 2026-10-22T07:10:02Z */ updated_at: string; }; }; responses: { /** @description Missing, unknown or expired API key, or a key refused by its environment: a sandbox key (`sk_nozle_test_`, `pk_nozle_test_`) on a live organization, a live key on a sandbox, or a key of a reset sandbox. The body does not say which. A `401` carries no `X-Nozle-Livemode` header. */ Unauthorized: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["ApiErrorUnauthorized"]; }; }; /** @description Unprocessable entity error */ UnprocessableEntity: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["ApiErrorUnprocessableEntity"]; }; }; /** @description Bad Request error */ BadRequest: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["ApiErrorBadRequest"]; }; }; /** @description Forbidden */ Forbidden: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["ApiErrorForbidden"]; }; }; /** @description Not Found error */ NotFound: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["ApiErrorNotFound"]; }; }; /** @description The request is refused in the resource's current state (for example a voided invoice). The `code` says why. */ NotAllowed: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["ApiErrorNotAllowed"]; }; }; /** @description The request is missing a field or has an invalid value. */ EngineBadRequest: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; /** @description Missing, malformed or unknown API key, or a key refused by its environment: a sandbox key (`sk_nozle_test_`, `pk_nozle_test_`) on a live organization, a live key on a sandbox, or a key of a reset sandbox. The body is `{"error": "invalid api key"}` in each case, without `X-Nozle-Livemode`. */ EngineUnauthorized: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; /** @description The key may not call this operation, for example a publishable key. */ EngineForbidden: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; /** @description The customer, subscription or resource was not found. */ EngineNotFound: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; /** @description The idempotency key was used with a different request, or the resource state conflicts. */ EngineConflict: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; /** @description The request is valid but breaks a product rule. */ EngineUnprocessable: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; /** @description Engine 2.22.0. `customer_payment_overdue`: the customer's unpaid invoices are past the grace of their plan and their [dunning policy](/guides/billing/dunning) ends with `block`. Nothing is tracked and the provider is not called. Do not retry: the next request after the invoices are paid, voided or credited works. A suspended workspace gets `workspace_suspended` instead; see [Errors](/api/errors#workspace-billing-errors). */ EngineCustomerPaymentOverdue: { headers: { [name: string]: unknown; }; content: { /** * @example { * "code": "customer_payment_overdue", * "error": "This customer's invoices are unpaid past their grace period. Usage resumes once they are paid." * } */ "application/json": components["schemas"]["EngineError"]; }; }; /** @description `invalid_request`: `X-Nozle-Customer-Id` is missing, or the request body could not be read. In the OpenAI error shape from Engine 2.22.0. */ OpenAIProxyBadRequest: { headers: { [name: string]: unknown; }; content: { /** * @example { * "error": { * "message": "missing X-Nozle-Customer-Id header", * "type": "invalid_request_error", * "code": "invalid_request" * }, * "code": "invalid_request" * } */ "application/json": components["schemas"]["OpenAIProxyError"]; }; }; /** @description `unauthorized`: `X-Nozle-Key` is missing or unknown. In the OpenAI error shape from Engine 2.22.0. */ OpenAIProxyUnauthorized: { headers: { [name: string]: unknown; }; content: { /** * @example { * "error": { * "message": "invalid nozle key", * "type": "authentication_error", * "code": "unauthorized" * }, * "code": "unauthorized" * } */ "application/json": components["schemas"]["OpenAIProxyError"]; }; }; /** @description `customer_payment_overdue` (Engine 2.22.0): the customer's unpaid invoices are past the grace of their plan and their [dunning policy](/guides/billing/dunning) ends with `block`; the provider is not called. `workspace_suspended` or `card_required`: your workspace is blocked by Nozle, see [Errors](/api/errors#workspace-billing-errors). Do not retry. In the OpenAI error shape from Engine 2.22.0. */ OpenAIProxyPaymentRequired: { headers: { [name: string]: unknown; }; content: { /** * @example { * "error": { * "message": "This customer's invoices are unpaid past their grace period. Usage resumes once they are paid.", * "type": "payment_required", * "code": "customer_payment_overdue" * }, * "code": "customer_payment_overdue" * } */ "application/json": components["schemas"]["OpenAIProxyError"]; }; }; /** @description `publishable_key_not_allowed` (a publishable key) or `permission_denied` (the key cannot write events). In the OpenAI error shape from Engine 2.22.0. */ OpenAIProxyForbidden: { headers: { [name: string]: unknown; }; content: { /** * @example { * "error": { * "message": "API key requires event:write permission", * "type": "permission_error", * "code": "permission_denied" * }, * "code": "permission_denied" * } */ "application/json": components["schemas"]["OpenAIProxyError"]; }; }; /** @description No subscription to bill. `active_subscription_not_found` when the customer is unknown, has no active subscription, or `X-Nozle-Subscription` names no active subscription of the customer; `active_subscription_ambiguous` when the customer has several active subscriptions and no `X-Nozle-Subscription`. The provider is not called. In the OpenAI error shape from Engine 2.22.0. */ OpenAIProxyNoSubscription: { headers: { [name: string]: unknown; }; content: { /** * @example { * "error": { * "message": "customer has multiple active subscriptions; set X-Nozle-Subscription", * "type": "invalid_request_error", * "code": "active_subscription_ambiguous" * }, * "code": "active_subscription_ambiguous" * } */ "application/json": components["schemas"]["OpenAIProxyError"]; }; }; /** @description `unavailable`: the key, the subscription or the customer payment state could not be read. The provider is not called. Retry later. In the OpenAI error shape from Engine 2.22.0. */ OpenAIProxyUnavailable: { headers: { [name: string]: unknown; }; content: { /** * @example { * "error": { * "message": "subscription lookup is unavailable", * "type": "api_error", * "code": "unavailable" * }, * "code": "unavailable" * } */ "application/json": components["schemas"]["OpenAIProxyError"]; }; }; /** @description `invalid_request`: `X-Nozle-Customer-Id` is missing, or the request body could not be read. In the Anthropic error shape from Engine 2.22.0. */ AnthropicProxyBadRequest: { headers: { [name: string]: unknown; }; content: { /** * @example { * "type": "error", * "error": { * "type": "invalid_request_error", * "message": "missing X-Nozle-Customer-Id header", * "code": "invalid_request" * }, * "code": "invalid_request" * } */ "application/json": components["schemas"]["AnthropicProxyError"]; }; }; /** @description `unauthorized`: `X-Nozle-Key` is missing or unknown. In the Anthropic error shape from Engine 2.22.0. */ AnthropicProxyUnauthorized: { headers: { [name: string]: unknown; }; content: { /** * @example { * "type": "error", * "error": { * "type": "authentication_error", * "message": "invalid nozle key", * "code": "unauthorized" * }, * "code": "unauthorized" * } */ "application/json": components["schemas"]["AnthropicProxyError"]; }; }; /** @description `customer_payment_overdue` (Engine 2.22.0): the customer's unpaid invoices are past the grace of their plan and their [dunning policy](/guides/billing/dunning) ends with `block`; the provider is not called. `workspace_suspended` or `card_required`: your workspace is blocked by Nozle, see [Errors](/api/errors#workspace-billing-errors). Do not retry. In the Anthropic error shape from Engine 2.22.0. */ AnthropicProxyPaymentRequired: { headers: { [name: string]: unknown; }; content: { /** * @example { * "type": "error", * "error": { * "type": "billing_error", * "message": "This customer's invoices are unpaid past their grace period. Usage resumes once they are paid.", * "code": "customer_payment_overdue" * }, * "code": "customer_payment_overdue" * } */ "application/json": components["schemas"]["AnthropicProxyError"]; }; }; /** @description `publishable_key_not_allowed` (a publishable key) or `permission_denied` (the key cannot write events). In the Anthropic error shape from Engine 2.22.0. */ AnthropicProxyForbidden: { headers: { [name: string]: unknown; }; content: { /** * @example { * "type": "error", * "error": { * "type": "permission_error", * "message": "API key requires event:write permission", * "code": "permission_denied" * }, * "code": "permission_denied" * } */ "application/json": components["schemas"]["AnthropicProxyError"]; }; }; /** @description No subscription to bill. `active_subscription_not_found` when the customer is unknown, has no active subscription, or `X-Nozle-Subscription` names no active subscription of the customer; `active_subscription_ambiguous` when the customer has several active subscriptions and no `X-Nozle-Subscription`. The provider is not called. In the Anthropic error shape from Engine 2.22.0. */ AnthropicProxyNoSubscription: { headers: { [name: string]: unknown; }; content: { /** * @example { * "type": "error", * "error": { * "type": "invalid_request_error", * "message": "customer has multiple active subscriptions; set X-Nozle-Subscription", * "code": "active_subscription_ambiguous" * }, * "code": "active_subscription_ambiguous" * } */ "application/json": components["schemas"]["AnthropicProxyError"]; }; }; /** @description `unavailable`: the key, the subscription or the customer payment state could not be read. The provider is not called. Retry later. In the Anthropic error shape from Engine 2.22.0. */ AnthropicProxyUnavailable: { headers: { [name: string]: unknown; }; content: { /** * @example { * "type": "error", * "error": { * "type": "api_error", * "message": "subscription lookup is unavailable", * "code": "unavailable" * }, * "code": "unavailable" * } */ "application/json": components["schemas"]["AnthropicProxyError"]; }; }; /** @description A dependency is busy or unavailable. Retry after the Retry-After seconds when the header is present. */ EngineUnavailable: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["EngineError"]; }; }; }; parameters: { /** @description Core 11.10.0 (on the Engine host, Engine 2.21.0). ISO 4217 code. Lists only plans in this currency, with or without a plan family. An unknown currency returns `422` with `currency: [value_is_invalid]`. On the Engine, a repeated value, one longer than 255 bytes or one with a control character returns `400 invalid_request`. */ plans_currency: string; /** @description Core 11.10.0 (on the Engine host, Engine 2.21.0). Secret keys only. Without `currency`, lists plans in this customer's locked currency. Ignored for an unknown customer, a customer without a currency yet, and an organization that allows several currencies per customer. A publishable key never reads a customer (the Engine drops the parameter). A customer-scoped Engine request lists for its own customer and returns `403 customer_scope_mismatch` when this names another one. */ plans_external_customer_id: string; /** @description The plan code. Every version of a plan keeps its code. */ plan_version_code: string; /** @description The `nozle_id` of the migration. */ plan_version_migration_id: string; /** @description Page number. */ page: number; /** @description Number of records per page. */ per_page: number; /** @description Unique identifier assigned to the customer in your application. */ external_customer_id: string; /** @description External subscription ID */ external_subscription_id: string; /** @description Show data only for given number of months. */ months: number; /** @description The customer external unique identifier (provided by your own application) */ external_customer_id_path: string; /** @description Filter by payment status. Possible values are `pending`, `failed` or `succeeded`. */ payment_status: "pending" | "failed" | "succeeded"; /** @description A unique wallet identifier within a customer. It is either set by the user at creation or auto-generated by Nozle if not provided. */ wallet_code: string; /** @description Unique identifier assigned to the invoice within the Nozle application. This ID is exclusively created by Nozle and serves as a unique identifier for the invoice's record within the Nozle system. */ invoice_id: string; /** @description Filter the results by currency, expressed as an ISO 4217 code. */ currency: string; /** @description Code of the existing plan. */ plan_code: string; /** @description Code of the existing charge. */ charge_code: string; /** @description Unique identifier of the charge filter. */ charge_filter_id: string; /** @description Code of the existing fixed charge. */ fixed_charge_code: string; /** @description Filter by subscription status. When provided, the subscription is looked up with this status instead of the default `active` status. Possible values are `pending`, `active`, `terminated`, or `canceled`. */ subscription_status: "pending" | "active" | "terminated" | "canceled"; /** @description External ID of the existing subscription. */ subscription_external_id_path: string; /** @description Unique id of the webhook. It is the same on every attempt, so use it to deduplicate. */ webhook_id: string; /** @description Unix time in seconds of this attempt. Reject a request more than 300 seconds off your clock. */ webhook_timestamp: string; /** @description Space-separated list of signatures, each `v1,`, from the endpoint secret. Two are sent while a secret is being rotated. */ webhook_signature: string; }; requestBodies: never; headers: never; pathItems: never; } /** * Customer tax data. The ID types are Stripe's list; Core owns validation (`value_is_invalid`, * `value_is_mandatory`, `invalid_format`), so a type a newer Core adds still type-checks as a plain string. */ declare const TAX_ID_TYPES: readonly ["ad_nrt", "ae_trn", "al_tin", "am_tin", "ao_tin", "ar_cuit", "au_abn", "au_arn", "ba_tin", "bb_tin", "bg_uic", "bh_vat", "bo_tin", "br_cnpj", "br_cpf", "bs_tin", "by_tin", "ca_bn", "ca_gst_hst", "ca_pst_bc", "ca_pst_mb", "ca_pst_sk", "ca_qst", "cd_nif", "ch_uid", "ch_vat", "cl_tin", "cn_tin", "co_nit", "cr_tin", "de_stn", "do_rcn", "ec_ruc", "eg_tin", "es_cif", "eu_oss_vat", "eu_vat", "gb_vat", "ge_vat", "gn_nif", "hk_br", "hr_oib", "hu_tin", "id_npwp", "il_vat", "in_gst", "is_vat", "jp_cn", "jp_rn", "jp_trn", "ke_pin", "kg_tin", "kh_tin", "kr_brn", "kz_bin", "li_uid", "li_vat", "ma_vat", "md_vat", "me_pib", "mk_vat", "mr_nif", "mx_rfc", "my_frp", "my_itn", "my_sst", "ng_tin", "no_vat", "no_voec", "np_pan", "nz_gst", "om_vat", "pe_ruc", "ph_tin", "ro_tin", "rs_pib", "ru_inn", "ru_kpp", "sa_vat", "sg_gst", "sg_uen", "si_tin", "sn_ninea", "sr_fin", "sv_nit", "th_vat", "tj_tin", "tr_tin", "tw_vat", "tz_vat", "ua_vat", "ug_tin", "us_ein", "uy_ruc", "uz_tin", "uz_vat", "ve_rif", "vn_tin", "za_vat", "zm_tin", "zw_tin"]; /** A tax ID type. Known values autocomplete; any other string is accepted so a new Core value does not break callers. */ type TaxIdType = (typeof TAX_ID_TYPES)[number] | (string & {}); /** `unverified` (stored, not checked), `pending` (VIES check running), `valid`, `invalid`. */ type TaxIdStatus = "unverified" | "pending" | "valid" | "invalid"; /** How tax applies to the customer: `provider` is an external tax provider, `pending` a VIES hold, `none` no EU tax management. */ type TaxTreatment = "standard" | "reverse_charge" | "exempt" | "provider" | "pending" | "none"; type CustomerType = "company" | "individual"; interface CustomerAddress { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; /** ISO 3166-1 alpha-2, for example `DE`. */ country?: string; } interface CustomerTaxId { type: TaxIdType; value: string; } /** Tax fields Core adds to a customer; present on Core versions that support customer tax data. */ interface CustomerTaxFields { tax_identification_type?: TaxIdType | null; tax_identification_status?: TaxIdStatus; /** True when the customer is exempt from tax. */ tax_exempt?: boolean; tax_treatment?: TaxTreatment; /** Non-blocking notes on a write, for example `country_mismatch`. Only on upsert responses. */ tax_identification_warnings?: string[]; } /** Invoice tax fields Core adds on finalization; `tax_details` is null on older invoices. */ interface InvoiceTaxFields { tax_status?: "pending" | "succeeded" | "failed" | null; tax_treatment?: TaxTreatment; tax_details?: InvoiceTaxDetails | null; } interface InvoiceTaxDetails { treatment?: TaxTreatment; tax_identification_number?: string | null; tax_identification_type?: TaxIdType | null; tax_identification_status?: TaxIdStatus; tax_identification_consultation_number?: string | null; customer_country?: string | null; seller_tax_identification_number?: string | null; /** Set when Stripe Tax computed the tax. */ provider?: "stripe_tax" | null; calculation_id?: string | null; transaction_id?: string | null; taxability_reasons?: string[] | null; } /** * Error thrown when a call returns a non-2xx response. The message is * ` failed: `, followed by `: ` when Nozle sent one; * `code` and `errorDetails` carry the rest of what Nozle returned. */ declare class NozleApiError extends Error { readonly status: number; /** Top-level `code`, for example `payment_provider_required`, `validation_errors` or `invalid_date_range`. */ readonly code?: string; /** Raw `error_details` object of a `validation_errors` response, for example `{ base: ["razorpay_requires_inr"] }`. */ readonly errorDetails?: Record; /** The `X-Request-Id` response header, when the service sent one. Quote it to support. */ readonly requestId?: string; /** Seconds to wait before retrying, from the `Retry-After` header, when the service sent one. */ readonly retryAfter?: number; /** Seconds to wait, from the body's `retry_after_seconds` (a 409 `customer_tax_check_pending`), when Core sent one. */ readonly retryAfterSeconds?: number; /** Set by `track()`: the event's transaction ID. Pass it back as `transactionId` when you retry, so the event is recorded once. */ transactionId?: string; constructor(operation: string, response: { status: number; statusText: string; headers?: Pick; }, body?: unknown); /** True when `code` equals the value, or the value is listed in `errorDetails` (for example `razorpay_requires_inr`). */ hasCode(code: string): boolean; /** * Positions of the events a `/events/batch` refused with this code, when every event was refused (402, nothing * stored). A partial batch is a 200; read it with {@link refusedEventIndexes}. */ refusedEventIndexes(code: string): number[]; } /** Thrown before any request when a call's own arguments are invalid (for example a bad `trackBatch()` event). */ declare class NozleValidationError extends Error { /** Position of the offending event in a batch call, when the problem is one event's. */ readonly index?: number; constructor(message: string, index?: number); } /** `error_details` of a `/events/batch` answer: field errors keyed by the event's index in the request. */ type EventBatchErrorDetails = Record>; /** A `/events/batch` 200: the stored events, and `error_details` for the events refused by index (the others were stored). */ interface EventBatchResponse> { events: Event[]; error_details?: EventBatchErrorDetails; } /** * Positions, ascending, that `error_details` of a `/events/batch` answer lists with this code, for example * `[2]` for `{ "2": { external_customer_id: ["customer_payment_overdue"] } }`. Pass a 200 body's `error_details`. */ declare function refusedEventIndexes(details: unknown, code: string): number[]; /** * True for a `customer_payment_overdue` refusal: a `NozleApiError` with the code, or a provider SDK error from the * LLM proxy with `status` 402 and the code in `code` or in the parsed body `error.code` (the Anthropic SDK keeps * the body there). Reads codes only. */ declare function isCustomerPaymentOverdue(error: unknown): boolean; declare const CUSTOMER_PAYMENT_OVERDUE = "customer_payment_overdue"; /** The one code for a customer with no active subscription. Core's `subscription_not_found` counts as the same case in {@link NozleApiError.hasCode}. */ declare const NO_ACTIVE_SUBSCRIPTION = "active_subscription_not_found"; /** Codes of a refused trial update: 422 `error_details.trial` except `plan_change_pending` (409). Test with `error.hasCode(...)`. */ declare const TrialErrorCode: { readonly InvalidParams: "trial_invalid_params"; readonly NotActive: "trial_not_active"; readonly ExtensionTooLong: "trial_extension_too_long"; readonly EndInPast: "trial_end_in_past"; readonly PaymentMethodRequired: "payment_method_required"; readonly PlanChangePending: "plan_change_pending"; }; type TrialErrorCode = (typeof TrialErrorCode)[keyof typeof TrialErrorCode]; /** * Codes for customer tax data. `ValueIsInvalid`, `ValueIsMandatory` and `InvalidFormat` arrive in `errorDetails` * (`tax_identification_type` / `tax_identification_number`) of a 422 `customers.upsert`; `TaxLocationRequired` (422, * `errorDetails.customer`: `country_missing` or `address_missing`) and `TaxCheckPending` (409, see `retryAfterSeconds`) * refuse a checkout call. Test with `error.hasCode(...)`. */ declare const CustomerTaxErrorCode: { readonly ValueIsInvalid: "value_is_invalid"; readonly ValueIsMandatory: "value_is_mandatory"; readonly InvalidFormat: "invalid_format"; readonly TaxLocationRequired: "customer_tax_location_required"; readonly TaxCheckPending: "customer_tax_check_pending"; /** Invoice tax failures (see `tax_status: "failed"`). */ readonly TaxLocationInvalid: "customer_tax_location_invalid"; readonly TaxIdInvalid: "tax_id_invalid"; readonly StripeTaxNotAuthorized: "stripe_tax_not_authorized"; readonly StripeAccountRequired: "stripe_account_required"; readonly TaxProviderUnavailable: "tax_provider_unavailable"; }; type CustomerTaxErrorCode = (typeof CustomerTaxErrorCode)[keyof typeof CustomerTaxErrorCode]; /** Codes of a refused `events.void`, and of a `track` of a voided ID. Test with `error.hasCode(...)`. */ declare const EventVoidErrorCode: { readonly EventNotFound: "event_not_found"; readonly PeriodInvoiced: "period_invoiced"; readonly ReasonRequired: "reason_required"; readonly TransactionVoided: "transaction_voided"; }; type EventVoidErrorCode = (typeof EventVoidErrorCode)[keyof typeof EventVoidErrorCode]; /** * Why Core refused `customers.erase`: a 422 with these codes in `errorDetails.customer`. Test with `error.hasCode(...)`. */ declare const CustomerEraseErrorCode: { readonly HasActiveSubscriptions: "has_active_subscriptions"; readonly HasDraftInvoices: "has_draft_invoices"; readonly HasUnpaidInvoices: "has_unpaid_invoices"; }; type CustomerEraseErrorCode = (typeof CustomerEraseErrorCode)[keyof typeof CustomerEraseErrorCode]; /** True when the error means the customer has no active subscription, whichever service or SDK path raised it. */ declare function isNoActiveSubscription(error: unknown): boolean; /** * Why `can()`, `usage.check()`, `usage.track()` or a hold answers `allowed: false` (its `reason`), and the `code` of * the LLM proxy's 402/429 refusals. Compare exactly; a reason a newer Engine adds arrives as its plain string. */ declare const RefusalReason: { readonly FeatureNotFound: "feature_not_found"; readonly NoSubscription: "no_subscription"; readonly SubscriptionRequired: "subscription_required"; readonly NoEntitlement: "no_entitlement"; readonly UsageLimitExceeded: "usage_limit_exceeded"; readonly EconomicPolicyDenied: "economic_policy_denied"; readonly CustomerPaymentOverdue: "customer_payment_overdue"; readonly InsufficientCredits: "insufficient_credits"; readonly BudgetExceeded: "budget_exceeded"; }; type RefusalReason = (typeof RefusalReason)[keyof typeof RefusalReason]; /** A 402 `budget_exceeded`: a hard spend limit is used up. `budget` is the limit's standing when the response carried one. */ declare class BudgetExceededError extends NozleApiError { readonly budget?: Budget; constructor(operation: string, response: { status: number; statusText: string; headers?: Pick; }, body?: unknown); } /** A 429 `usage_limit_exceeded`: a hard unit limit is reached. */ declare class UsageLimitExceededError extends NozleApiError { constructor(operation: string, response: { status: number; statusText: string; headers?: Pick; }, body?: unknown); } interface NozleConfig { /** Organization credential. Defaults to the NOZLE_SECRET_KEY environment variable. */ apiKey?: string; /** Root URL of the Nozle API. Engine calls go to `${host}/engine` and Core calls to `${host}/core`. Defaults to https://api.nozle.app. */ host?: string; /** Engine URL. Overrides the engine address derived from `host`. */ baseUrl?: string; /** Core billing resources and subscription discovery. Overrides the Core address derived from `host`. */ eventsUrl?: string; /** Per-attempt timeout in milliseconds. Default 10000. */ timeout?: number; /** Extra attempts after a network error, timeout, 429 or 5xx. Default 0: no retries. Only requests that are safe to repeat are retried: reads, calls with an idempotency key, and event, cost event and customer writes. */ maxRetries?: number; /** First retry delay in milliseconds, doubled each retry up to 10 seconds, or the `Retry-After` header when sent. Default 500. */ retryDelayMs?: number; } interface TrackOptions { subscriptionId?: string; transactionId?: string; timestamp?: string; } /** One event of {@link Nozle.trackBatch}: the arguments of `track()` as an object. */ interface TrackBatchEvent { customerId: string; event: string; metadata?: Record; subscriptionId?: string; /** Generated (UUID v7) when missing, and returned in the result. Must be unique within the call. */ transactionId?: string; /** RFC 3339 or Unix seconds, as for `track()`. Each event keeps its own; none is shifted or clamped. */ timestamp?: string; } interface TrackBatchOptions { /** Events per request, 1 to 5000 (the Engine 2.28.0+ maximum; default 5000). A lower Engine cap is handled by splitting. */ chunkSize?: number; /** Requests in flight at once, 1 to 64 (default 4). */ concurrency?: number; } /** The outcome of one event of {@link Nozle.trackBatch}, at the same position as in the input. */ type TrackBatchEventResult = { index: number; transactionId: string; status: "accepted"; } /** Engine refused this event; `errors` maps a field to codes, for example `{ code: ["value_is_mandatory"] }`. Do not resend it unchanged. */ | { index: number; transactionId: string; status: "rejected"; errors: Record; } /** The request carrying it failed (`NozleApiError`, network error or timeout) and it may or may not be stored. Resend it with the same `transactionId`. */ | { index: number; transactionId: string; status: "failed"; error: unknown; }; interface TrackBatchResult { total: number; accepted: number; rejected: number; failed: number; /** One entry per input event, in input order. */ results: TrackBatchEventResult[]; } interface CostEventParams { costMeterCode: string; costEventId?: string; parentTransactionId?: string; externalCustomerId?: string; requestId?: string; operationKey?: string; properties?: Record; timestamp?: number; } interface CostEventAccepted { status: "accepted"; cost_event_id: string; } /** * Which subscription `can()` evaluates, for a customer with several. Without either, the customer's one * subscription is used; with several, the result is `allowed: false, reason: "subscription_required"`. */ interface CanOptions { /** External id of the subscription. */ subscriptionId?: string; /** External id of the Entity whose subscription is evaluated. */ entityId?: string; } interface CanResult { allowed: boolean; /** * Denial code when `allowed` is `false`, one of {@link RefusalReason}: `feature_not_found`, `no_subscription`, * `subscription_required`, `no_entitlement`, `usage_limit_exceeded`, `economic_policy_denied`, * `customer_payment_overdue` (the customer's unpaid invoices are past the plan's grace; `used` is `0` and * `limit`/`remaining` are `null`) or `budget_exceeded` (a hard spend limit is used up; see `budget`). */ reason?: RefusalReason | (string & {}); feature_type?: string; configuration?: Record; used: number; /** `null` when the feature has no limit. */ limit: number | null; /** `null` when the feature has no limit. */ remaining: number | null; overage?: boolean; economics?: CanEconomics; policy?: CanPolicy; /** The spend limit that refused the call (`budget_exceeded`), else the tightest one covering the Feature (Engine 2.34.0+). */ budget?: Budget; } /** * One money budget (spend limit) and its standing in the current period. Amounts are decimal strings in major units * of `currency`. */ interface Budget { /** The Feature the limit covers; `null` for the subscription's total limit. */ feature_code: string | null; limit: string; /** Gross metered usage charges booked this period. */ spent: string; /** Spend reserved by open budget holds. */ held: string; remaining: string; currency: string; period: "billing_period" | "calendar_month" | "lifetime"; period_start: string; /** `null` for a `lifetime` limit. */ period_end: string | null; /** A `soft` limit never refuses. */ mode: "hard" | "soft"; /** `warning` once a threshold is reached, `exceeded` once spent plus held reaches the limit. */ status: "ok" | "warning" | "exceeded"; /** Time of the latest event booked into `spent` (usage reaches the Engine a few seconds late); `null` before any. */ as_of: string | null; /** When counting began: `period_start` once earlier spend in the period is counted, else when the count started; `null` before any. Engine 2.38.0. */ counted_from?: string | null; } interface BudgetListOptions { /** External id of the subscription, for a customer with several. */ subscriptionId?: string; } /** `GET /customers/{id}/budgets`: every spend limit of the subscription. */ interface BudgetList { customer_id: string; subscription_id: string; budgets: Budget[]; } interface CanEconomics { status: "estimated" | "not_configured" | "unavailable" | "stale"; currency?: string; estimated_incremental_cost?: string; estimated_incremental_revenue?: string; estimated_incremental_margin?: string; estimated_margin_percent?: string; rule_version_ids?: string[]; includes?: string[]; excludes?: string[]; reason?: string; calculated_at: string; } interface CanPolicy { version_id: string; mode: "allow" | "warn" | "deny"; on_unavailable: "allow" | "warn" | "deny"; /** What the policy does for a feature with no Cost Rule. Engine 2.39.0; absent on older Engines. */ on_not_configured?: "allow" | "warn" | "deny"; /** Target of the policy that decided the call. Engine 2.40.0; absent on older Engines. */ scope?: "customer" | "plan" | "feature" | "organization"; minimum_margin_amount?: string; minimum_margin_percent?: string; maximum_estimated_cost?: string; maximum_snapshot_age_seconds: number; decision: "allow" | "warn" | "deny"; reason: string; } type PlanStatus = "active" | "archived"; interface Plan { code: string; name: string; amount_cents: number; amount_currency: string; interval: string; /** The version of the code this plan is (plan versioning). `plans()` returns current versions only. */ version?: number; /** Whether new subscriptions get this version. */ is_current?: boolean; /** `archived` plans take no new subscriptions; their existing subscriptions keep billing (Core 11.51.0). */ status?: PlanStatus; /** When the plan was archived, `null` while it is active (Core 11.51.0). */ archived_at?: string | null; /** The plan family this plan is a variant of. Absent for a plan without a family. */ family?: PlanFamilyRef; /** Every current variant of the family: one price per interval and currency. Absent for a plan without a family. */ prices?: PlanPrice[]; } /** A plan's family as the catalog returns it: the currencies it is sold in, in order, and the default one. */ interface PlanFamilyRef { code: string; currencies: string[]; default_currency: string; } /** One variant of a plan family: the plan sold for an interval in a currency. */ interface PlanPrice { currency: string; interval: string; plan_code: string; amount_cents: number; } interface PlansOptions { /** A secret key gets every plan; `false` gets the pricing table view a publishable key gets. */ includeHidden?: boolean; /** Lists only plans in this ISO currency. An unknown currency is a 422. */ currency?: string; /** * Secret key only: lists only plans in this customer's locked currency when `currency` is not given. Ignored when * the organization allows several currencies per customer. */ externalCustomerId?: string; /** Secret key only: `active` or `archived` lists one kind (Core 11.51.0). Without it a secret key gets both; a publishable key never gets archived plans. */ status?: PlanStatus; } /** * Sells a plan family's variant instead of a plan code: Core picks the family's current plan for the interval and * currency. Without `currency` it uses the customer's locked currency, else the family's default. */ interface PlanFamilySelection { planFamilyCode: string; interval: string; currency?: string; } interface RazorpayCheckoutResult { type: "razorpay"; checkout_id: string; key_id: string; order_id: string; amount_cents: number; currency: string; expires_at?: string; /** Set for an invoice checkout. A paid upgrade returns `plan_upgrade_intent_id` instead. */ invoice_id?: string; plan_upgrade_intent_id?: string; external_entity_id?: string; external_subscription_id?: string; /** Mandate checkout only: the Razorpay customer to pass to the modal with `recurring: "1"`. */ customer_id?: string; recurring?: boolean; mandate_max_amount_cents?: number; } /** * The checkout is not ready to collect payment yet: Razorpay while the order is * being created, and Stripe when a quoted upgrade is replayed while its webhook is * still pending. Recover with the checkout status call using `checkout_id`. */ interface ProcessingCheckoutResult { type: "processing"; checkout_id: string; status: string; amount_cents?: number; currency?: string; expires_at?: string; invoice_id?: string; plan_upgrade_intent_id?: string; } /** * A hosted payment page: the Stripe Checkout page or a Razorpay payment link. Redirect the customer to `url` * (`payment_url` is the same address). For a paid upgrade poll `checkoutStatus(plan_upgrade_intent_id, scope)` after they return. * A new subscription or invoice checkout has no status call: confirm through webhooks or by reloading billing state. * A Stripe `checkout_id` is the Stripe session id, not a status id. */ interface HostedCheckoutResult { type: "hosted"; url: string; payment_url: string; checkout_id?: string; amount_cents?: number; currency?: string; expires_at?: string; invoice_id?: string; plan_upgrade_intent_id?: string; external_entity_id?: string; external_subscription_id?: string; } /** * Stripe only: redirect the customer to `url`. A Razorpay customer pays each invoice by payment link, * so the call throws `NozleApiError` (status 422) where `hasCode("razorpay_pays_by_link")` is true. */ interface ManagePaymentMethodResult { url: string; expires_at: string | null; provider: "stripe"; } interface CheckoutOptions { idempotencyKey?: string; registerMandate?: boolean; externalEntityId?: string; /** External subscription identifier for a customer plan change. */ subscriptionId?: string; /** Opaque quote from previewSubscriptionChange; never reformat or inspect it. */ quoteId?: string; /** Where the hosted page sends a customer who leaves it. Validated like `returnUrl`; defaults to the return URL. A return URL may contain `{CHECKOUT_SESSION_ID}`. */ cancelUrl?: string; } interface SubscriptionCheckoutScope { customerId: string; subscriptionId: string; } interface SubscriptionPlan { code: string; name: string; amount_cents: number | string; currency: string; interval: string; } interface SubscriptionOptions { subscription: { id: string; external_id: string; plan_code: string; status: string; ending_at: string | null; plan: SubscriptionPlan; /** The version of the plan code the subscription is billed on. Set by the billing handler from Core. */ plan_version?: number | null; /** That version's entitlements (with its usage limits). Set by the billing handler; null when unavailable. */ entitlements?: unknown[] | null; }; pending_change: { id: string; plan_code: string; name: string; effective_at: string; plan: SubscriptionPlan; } | null; eligible_plans: Array; checkout?: { id: string; status: string; plan_code: string; } | null; } interface SubscriptionChangePreview { quote_id: string; currency: string; credit_amount_cents: number | string; debit_amount_cents: number | string; net_amount_cents: number | string; amount_due_now_cents: number | string; amount_due_at_effective_cents: number | string; transition_direction: "upgrade" | "downgrade"; timing: "immediate" | "end_of_period"; effective_at: string; renewal_at: string | null; } interface WithdrawPendingSubscriptionChangeResult { subscription: Pick; withdrawn_pending_subscription_id: string; replayed: boolean; } interface RazorpayVerification { razorpay_order_id: string; razorpay_payment_id: string; razorpay_signature: string; } interface CheckoutStatus { checkout_id: string; provider: "razorpay" | "stripe"; status: "processing" | "awaiting_payment" | "succeeded" | "failed" | "expired" | "needs_review"; fulfillment_status: "pending" | "processing" | "succeeded"; amount_cents: number; currency: string; invoice_id?: string | null; checkout?: CheckoutResult; } type CheckoutResult = RazorpayCheckoutResult | ProcessingCheckoutResult | HostedCheckoutResult | CompletedCheckoutResult | ScheduledCheckoutResult; /** The change is done: paid with credits, or nothing was due. */ interface CompletedCheckoutResult { type: "completed"; status: string; /** `credits` or `none`. */ payment_source?: string; subscription_id?: string; plan_code?: string; invoice_id?: string; amount_cents?: number; currency?: string; external_entity_id?: string; external_subscription_id?: string; checkout_id?: string; /** An immediate configured downgrade carries the settlement fields of a transition result. */ transition_direction?: string; transition_policy?: string; effective_at?: string; renewal_at?: string | null; amount_due_cents?: number | string; } /** The change takes effect later; `subscription_id` is the pending subscription. */ interface ScheduledCheckoutResult { type: "scheduled"; status: string; subscription_id?: string; plan_code?: string; /** `upgrade` or `downgrade`. */ transition_direction?: string; transition_policy?: string; effective_at?: string; external_entity_id?: string; external_subscription_id?: string; checkout_id?: string; } interface EntitySubscriptionPlan { code: string; name: string; interval: string; amount_cents: number; amount_currency: string; status: string; effective_at: string | null; } interface EntitySubscription { external_customer_id: string; external_entity_id: string; external_subscription_id: string; status: string; current_plan: EntitySubscriptionPlan | null; pending_plan: EntitySubscriptionPlan | null; billing_time: "calendar" | "anniversary" | null; subscription_at: string | null; started_at: string | null; current_period_start: string | null; current_period_end: string | null; ending_at: string | null; canceled_at: string | null; cancel_at_period_end: boolean | null; created_at: string; updated_at: string; } interface EntitySubscriptionList { entity_subscriptions: EntitySubscription[]; } interface EntitySubscriptionCheckoutParams { registerMandate?: boolean; planCode: string; returnUrl?: string; billingTime?: "calendar" | "anniversary"; idempotencyKey?: string; } interface EntitySubscriptionCheckoutItem { externalEntityId: string; planCode: string; } interface EntitySubscriptionCheckoutManyParams { items: EntitySubscriptionCheckoutItem[]; returnUrl?: string; billingTime?: "calendar" | "anniversary"; idempotencyKey: string; } interface EntitySubscriptionCheckoutItemResult { external_entity_id: string; external_subscription_id: string; plan_code: string; subscription_status: string; } interface EntitySubscriptionCheckoutManyResult { id: string; type: "hosted" | "razorpay" | "processing" | "completed"; checkout_id?: string; key_id?: string; order_id?: string; status: string; /** Hosted result: redirect the customer here. */ url?: string; payment_url?: string; invoice_id: string; amount_cents: number; currency: string; replayed: boolean; expires_at: string | null; items: EntitySubscriptionCheckoutItemResult[]; } interface EntitySubscriptionCancelParams { idempotencyKey: string; timing?: SubscriptionTransitionTiming; creditAction?: SubscriptionTransitionCreditAction; refundMode?: SubscriptionTransitionRefundMode; finalInvoiceAction?: SubscriptionTransitionFinalInvoiceAction; } interface EntitySubscriptionCancelResult { entity_subscription: EntitySubscription; subscription_transition: SubscriptionTransitionResult["subscription_transition"]; } interface SubscribeOptions { /** * The version of the plan code to sell instead of the current one. Another version of an existing subscription * fails with a 422 `plan_version_change_not_supported`; an unknown version with a 404 `plan_version_not_found`. */ planVersion?: number; } interface SubscribeResult { subscription_id: string; status: string; } type CancellationPolicy = "end_of_period" | "immediate"; /** Options of `cancelSubscription`. Each one left out follows the subscription, then the organization's cancellation settings. */ interface CancelSubscriptionOptions { /** When the subscription ends. Left out, the organization's cancellation timing applies. */ policy?: CancellationPolicy; creditAction?: SubscriptionTransitionCreditAction; refundMode?: SubscriptionTransitionRefundMode; finalInvoiceAction?: SubscriptionTransitionFinalInvoiceAction; } interface CancelSubscriptionResult { subscription: { external_id: string; status: string; ending_at: string | null; terminated_at?: string | null; }; } /** What `updateSubscription` does to a trial: exactly one of `extend_days`, `ends_at` or `convert`. */ type SubscriptionTrialUpdate = { reason?: string; } & ({ extend_days: number; ends_at?: never; convert?: never; } | { ends_at: string; extend_days?: never; convert?: never; } | { convert: true; extend_days?: never; ends_at?: never; }); /** Result of `updateSubscription`: the subscription with its trial state. */ interface UpdateSubscriptionResult { subscription: CoreSubscription & { /** When the trial ends (ISO 8601), or null when the subscription has no trial. */ trial_ends_at: string | null; in_trial: boolean; }; } /** What a void did to each downstream record: `pending` while its async step runs, `not_applicable` when nothing to undo. */ interface EventVoidEffects { event: "voided"; usage: "reversed" | "recomputed" | "not_applicable" | "pending"; credits: "refunded" | "not_applicable" | "pending"; cost: "reversed" | "not_applicable" | "pending"; margin: "reversed" | "not_applicable" | "pending"; } interface EventVoid { transaction_id: string; /** `voided` for this call, `already_voided` for a replay (no side effects). */ status: "voided" | "already_voided"; reason: string; /** ISO 8601, server time. */ voided_at: string; /** `api_key:`. */ actor: string; effects: EventVoidEffects; } /** Result of `events.void`. */ interface EventVoidResult { void: EventVoid; } type SubscriptionTransitionOperation = "cancel" | "downgrade" | "uncancel"; type SubscriptionTransitionTiming = "end_of_period" | "immediate"; type SubscriptionTransitionBillingAnchor = "keep_anchor" | "reset_anchor"; type SubscriptionTransitionProrationBehavior = "prorate_immediately" | "none"; type SubscriptionTransitionCreditAction = "credit" | "refund" | "offset" | "none"; type SubscriptionTransitionRefundMode = "prorated" | "full"; type SubscriptionTransitionFinalInvoiceAction = "generate" | "skip"; interface SubscriptionTransitionParams { customerId: string; subscriptionId: string; operation: SubscriptionTransitionOperation; timing?: SubscriptionTransitionTiming; targetPlanCode?: string; billingAnchor?: SubscriptionTransitionBillingAnchor; prorationBehavior?: SubscriptionTransitionProrationBehavior; creditAction?: SubscriptionTransitionCreditAction; refundMode?: SubscriptionTransitionRefundMode; finalInvoiceAction?: SubscriptionTransitionFinalInvoiceAction; /** For end-of-period cancellation, reject a changed confirmation date atomically. */ expectedEffectiveAt?: string; /** Opaque plan-change quote; only valid for a downgrade transition. */ quoteId?: string; } interface SubscriptionTransitionPreview { subscription_transition: { operation: SubscriptionTransitionOperation; timing: SubscriptionTransitionTiming; billing_anchor: SubscriptionTransitionBillingAnchor; proration_behavior: SubscriptionTransitionProrationBehavior; credit_action: SubscriptionTransitionCreditAction; refund_mode: SubscriptionTransitionRefundMode; final_invoice_action: SubscriptionTransitionFinalInvoiceAction; effective_at: string; renewal_at?: string | null; credit_amount_cents: number; refund_amount_cents: number; offset_amount_cents: number; amount_due_cents: number; currency: string; }; } interface SubscriptionTransitionResult { subscription_transition: { id: string; replayed: boolean; operation: SubscriptionTransitionOperation; timing: SubscriptionTransitionTiming; billing_anchor: SubscriptionTransitionBillingAnchor; proration_behavior: SubscriptionTransitionProrationBehavior; credit_action: SubscriptionTransitionCreditAction; refund_mode: SubscriptionTransitionRefundMode; final_invoice_action: SubscriptionTransitionFinalInvoiceAction; effective_at: string; subscription_id?: string; external_subscription_id?: string; plan_code?: string; status?: string; credit_note_id?: string; credit_amount_cents: number; refund_amount_cents: number; offset_amount_cents: number; invoice_id?: string; amount_due_cents: number; currency?: string; }; } interface MarginQueryParams { from?: string; to?: string; [key: string]: string | undefined; } interface TrendParams extends MarginQueryParams { granularity?: "hour" | "day" | "week" | "month"; } interface PingResult { ok: boolean; engine: string; } interface CustomerBillingConfiguration { /** Payment provider type, e.g. `"stripe"`. */ paymentProvider: string; /** Code of the payment provider connection in Nozle. */ paymentProviderCode?: string; /** Existing customer ID at the provider, e.g. a Stripe `cus_…`. Links it without creating a new one. */ providerCustomerId?: string; /** Create the customer at the provider when no `providerCustomerId` is given. */ syncWithProvider?: boolean; providerPaymentMethods?: string[]; } interface CustomerUpsertParams { externalId: string; name?: string; email?: string; billingConfiguration?: CustomerBillingConfiguration; customerType?: CustomerType; legalName?: string; address?: CustomerAddress; shippingAddress?: CustomerAddress; /** Exempt the customer from tax. */ taxExempt?: boolean; /** `null` clears the stored tax ID (and its type and check result). Core validates the format. */ taxId?: CustomerTaxId | null; } interface CustomerUpsertResult extends CustomerTaxFields { external_id: string; name?: string; email?: string; /** When `customers.erase` erased the customer's personal data, `null` before (Core 11.52.0). */ erased_at?: string | null; } interface CheckAndDeductParams { customerId: string; /** @deprecated Ignored: it is not sent, because the deduction depends only on the customer's wallet and `credits`. */ feature?: string; credits: number; } interface CheckAndDeductResult { allowed: boolean; remaining: number; } interface CreditSystem { id: string; code: string; name: string; description: string | null; unitName: string; status: string; createdAt: string; updatedAt: string; } interface CreditBalanceSource { id: string; entity_id?: string | null; parent_source_id?: string | null; scope?: "customer" | "entity"; transferable?: boolean; returnable?: boolean; type: "subscription_grant" | "top_up" | "manual_grant" | "adjustment" | "allocated_top_up"; reference: string; subscription_id: string | null; initial: string; remaining: string; valid_from: string; /** Credits of this source reserved by open holds (Engine 2.34.0+). */ held?: string; expires_at: string | null; priority: number; status: string; available: boolean; } interface CreditBalance { customer_id: string; credit_system: string; credit_system_id: string; credit_system_name: string; unit_name: string; system_status: string; /** What can be spent now: open holds are already subtracted. */ available: string; /** Credits reserved by open holds (Engine 2.34.0+). */ held?: string; as_of: string; sources: CreditBalanceSource[]; } interface CreditBalances { customer_id: string; as_of: string; balances: CreditBalance[]; } interface CreditOperationAllocation { source_id: string; source_entity_id?: string | null; source_type: string; delta: string; before: string; after: string; } interface CreditOperation { id: string; entity_id?: string | null; credit_system: string; credit_system_id: string; credit_system_name: string; unit_name: string; feature_code: string | null; type: "consume" | "grant" | "adjustment" | "expire" | "revoke" | "refund" | "transfer"; status: "succeeded" | "denied" | "reversed"; metric_amount: string | null; credit_amount: string; rate_id: string | null; rate_metric_amount: string | null; rate_credit_amount: string | null; reason: string | null; occurred_at: string; source_allocations: CreditOperationAllocation[]; } interface CreditOperationPage { customer_id: string; operations: CreditOperation[]; next_cursor: string | null; } interface CreditOperationQuery { creditSystemCode?: string; limit?: number; cursor?: string; } type CustomerEntityStatus = "active" | "suspended" | "deleted"; interface CustomerEntity { id: string; customer_id: string; external_id: string; name: string | null; status: CustomerEntityStatus; metadata: Record; created_at: string; updated_at: string; deleted_at: string | null; } interface CustomerEntityUpsertData { name?: string | null; status: CustomerEntityStatus; metadata?: Record; } interface CustomerEntityBulkUpsertItem extends CustomerEntityUpsertData { externalId: string; } interface IdempotentMutationOptions { idempotencyKey: string; } interface CustomerEntityMutationResult { action: "created" | "updated" | "unchanged" | "activated" | "reactivated" | "suspended" | "deleted"; entity: CustomerEntity; replayed: boolean; } interface CustomerEntityListQuery { status?: CustomerEntityStatus; limit?: number; cursor?: string; } interface CustomerEntityPage { customer_id: string; entities: CustomerEntity[]; next_cursor: string | null; } interface CustomerEntityBulkMutationCounts { created: number; updated: number; unchanged: number; activated: number; reactivated: number; suspended: number; deleted: number; } interface CustomerEntityBulkMutationResult { customer_id: string; entities: Array>; counts: CustomerEntityBulkMutationCounts; replayed: boolean; } type EntityCreditPoolPolicy = "entity_only" | "entity_then_customer" | "customer_only"; interface EntityCreditBalance extends Omit { entity_id: string; entity_status: CustomerEntityStatus; entity_available: string; shared_available: string; effective_available: string; /** Credits reserved by open holds: the entity's own, the shared pool's, and the pool the entity spends from (Engine 2.34.0+). */ entity_held?: string; shared_held?: string; held?: string; consumed: string; pool_policy: EntityCreditPoolPolicy | null; } interface EntityCreditBalances { customer_id: string; entity_id: string; entity_status: CustomerEntityStatus; as_of: string; balances: EntityCreditBalance[]; } interface EntityCreditOperationPage extends CreditOperationPage { entity_id: string; } interface EntityCreditTransferParams { creditSystemCode: string; amount: string; } interface EntityCreditTransferSource { source_id: string; parent_source_id?: string | null; source_type: "top_up" | "allocated_top_up"; scope: "customer" | "entity"; amount: string; before: string; after: string; expires_at: string | null; created?: boolean; } interface EntityCreditTransferResult { transferred: boolean; operation_id: string; customer_id: string; entity_id: string; credit_system: string; direction: "allocation" | "deallocation"; amount: string; available: string; reason?: string | null; parent_sources: EntityCreditTransferSource[]; entity_sources: EntityCreditTransferSource[]; replayed: boolean; } interface UsageCheckParams { customerId: string; entityId?: string; featureCode: string; creditSystemCode?: string; properties?: Record; occurredAt?: string; } interface UsageTrackParams { customerId: string; entityId?: string; featureCode: string; creditSystemCode?: string; properties?: Record; timestamp?: string; } interface UsageTrackOptions { idempotencyKey: string; } interface UsageDeduction { balance_source_id?: string; source_type: string; amount: string; remaining: string; } /** A `budget_exceeded` refusal carries only `allowed`, `reason` and `budget`. */ interface UsageCheckResult { advisory: true; allowed: boolean; metric_amount: string; credit_system: string; credits_required: string; available: string; projected_remaining?: string; projected_deductions?: UsageDeduction[]; reason?: RefusalReason | (string & {}); /** The used-up hard spend limit, with `reason` `budget_exceeded` (Engine 2.34.0+). */ budget?: Budget; } /** A `budget_exceeded` refusal carries only `allowed`, `reason` and `budget`. */ interface UsageTrackResult { allowed: boolean; operation_id?: string; metric_amount?: string; credit_system?: string; credits_required?: string; credits_consumed?: string; available?: string; remaining?: string; reason?: RefusalReason | (string & {}); deductions?: UsageDeduction[]; /** The used-up hard spend limit, with `reason` `budget_exceeded` (Engine 2.34.0+). */ budget?: Budget; } type UsageHoldStatus = "held" | "denied" | "finalized" | "released" | "expired"; /** The `usage.track` request plus how long the hold lasts. */ interface UsageHoldCreateParams extends UsageTrackParams { /** Seconds until the hold expires: 1 to 86400, Engine default 900. */ ttlSeconds?: number; } /** The actual usage of the held call. */ interface UsageHoldFinalizeParams { properties?: Record; timestamp?: string; } interface UsageHoldListOptions { status?: UsageHoldStatus; } /** A hold on credits: the Feature is billed in credits. */ interface CreditUsageHold { /** Engine sends no `kind` for a credit hold. */ kind?: undefined; hold_id: string; status: UsageHoldStatus; customer_id: string; entity_id?: string; subscription_id?: string; feature_code: string; credit_system: string; pool_policy?: string; metric_amount: string; credits_required: string; /** "0" for a denied hold. */ credits_held: string; expires_at: string; created_at: string; resolved_at: string | null; operation_id?: string; } /** * A budget hold (Engine 2.34.0+): the Feature is billed in money under a hard spend limit, so the hold reserves the * call's estimated spend. Finalize sends the usage as one event; its spend is then booked. */ interface BudgetUsageHold { kind: "budget"; hold_id: string; status: UsageHoldStatus; customer_id: string; subscription_id: string; feature_code: string; metric_amount: string; /** Spend reserved, a decimal string in major units of `currency`; "0" once released, expired or denied. */ amount_held: string; currency: string; expires_at: string; created_at: string; resolved_at: string | null; } /** A credit hold, or a budget hold when `kind` is `"budget"`. */ type UsageHold = CreditUsageHold | BudgetUsageHold; interface CreditUsageHoldCreateResult extends CreditUsageHold { allowed: boolean; reason?: RefusalReason | (string & {}); available: string; } interface BudgetUsageHoldCreateResult extends BudgetUsageHold { allowed: boolean; /** `budget_exceeded` when the estimated spend does not fit. */ reason?: RefusalReason | (string & {}); budget?: Budget; } type UsageHoldCreateResult = CreditUsageHoldCreateResult | BudgetUsageHoldCreateResult; interface CreditUsageHoldFinalizeResult extends UsageTrackResult { kind?: undefined; entity_id?: string; pool_policy?: string; hold_id: string; hold_status: UsageHoldStatus; credits_held: string; credits_released: string; /** The hold had expired, so the usage ran as a plain track. */ hold_expired: boolean; } /** A credit hold's finalize answers the track result; a budget hold's answers the hold itself (`kind` `"budget"`). */ type UsageHoldFinalizeResult = CreditUsageHoldFinalizeResult | BudgetUsageHold; interface UsageHoldList { customer_id: string; holds: UsageHold[]; } /** One subscription as Core returns it (`GET /subscriptions`). */ type CoreSubscription = components["schemas"]["SubscriptionObject"]; /** A customer's usage for one billing period (Core `current_usage`, or one `past_usage` period). */ type CustomerUsage = components["schemas"]["CustomerUsageObject"]; type Schemas$1 = components["schemas"]; /** `GET /margin/summary`. Amounts are integer cents. */ type MarginSummary = Schemas$1["MarginSummary"]; /** `GET /margin/customers`; `customers` is null when there are none. */ type MarginByCustomer = Schemas$1["MarginByCustomerResponse"]; /** `GET /margin/metrics`; `metrics` is null when there are none. */ type MarginByMetric = Schemas$1["MarginByMetricResponse"]; /** `GET /margin/plans`; `plans` is null when there are none. */ type MarginByPlan = Schemas$1["MarginByPlanResponse"]; /** `GET /margin/models`; `models` is null when there are none. */ type MarginByModel = Schemas$1["MarginByModelResponse"]; /** `GET /margin/trend`; `trend` is null when the range has no events. */ type MarginTrend = Schemas$1["MarginTrendResponse"]; /** Result of replaying one metric's usage at a new unit price (`POST /margin/simulate`). All amounts are integer cents. */ type MarginSimulation = Schemas$1["MarginSimulationResult"]; interface MarginSimulateParams { metricCode: string; /** New unit price in dollars, 0 or more. */ newPriceDollars: number; } interface CostIntelligenceReportParams { /** Inclusive start (RFC 3339). Defaults to 30 days before the request. */ from?: string; /** Exclusive end (RFC 3339). Defaults to the request time. */ to?: string; /** Rows per breakdown and detail list, 1 to 500 (server default 100). */ limit?: number; } /** Ledger-backed cost totals, breakdowns and review queues (`GET /cost-intelligence/report`). */ type CostIntelligenceReport = Schemas$1["CostIntelligenceReport"]; interface SharedCostAllocationParams { /** Start of the allocation period (RFC 3339). */ allocationPeriodStart: string; } type SharedCostAllocationPreview = Schemas$1["SharedCostAllocationPreview"]; type SharedCostAllocationRun = Schemas$1["SharedCostAllocationRun"]; /** Opening balance of a subscription imported with `importBillingState` (Engine `credit-balance-imports`). */ interface CreditBalanceImportParams { externalSubscriptionId: string; creditSystemCode: string; /** Decimal string, more than 0. */ grantedAmount: string; /** Decimal string, from 0 to `grantedAmount`. */ remainingAmount: string; externalEntityId?: string; /** Validate without writing. */ dryRun?: boolean; } type CreditBalanceImport = Schemas$1["CreditsBalanceImport"]; /** A subscription another system already bills (Core `billing-state-imports`). */ interface BillingStateImportParams { subscription: { planCode: string; status: "active"; billingAuthority: "external"; externalReference: string; /** RFC 3339; the period must contain the current time and span exactly one plan interval. */ currentPeriodStart: string; currentPeriodEnd: string; }; externalEntityId?: string; /** Validate without writing. */ dryRun?: boolean; } type BillingStateImport = Schemas$1["BillingStateImport"]; interface ImportOptions { /** Required, at most 255 bytes. Retry with the same key and an identical body. */ idempotencyKey: string; } /** * Why events left the buffer unsent: `buffer_full` (the queue held `maxQueueSize` events), `rejected` (Engine refused * the event; not retried), `failed` (its requests failed for `maxAttempts` flushes) or `closed` (tracked after `close()`). */ type EventBufferErrorCode = "buffer_full" | "rejected" | "failed" | "closed"; declare class EventBufferError extends Error { readonly code: EventBufferErrorCode; /** For `rejected`: Engine's codes by field, for example `{ code: ["value_is_mandatory"] }`. */ readonly errors?: Record; constructor(code: EventBufferErrorCode, message: string, details?: { errors?: Record; cause?: unknown; }); } interface EventBufferOptions { /** Events per `/events/batch` request, 1 to 5000 (default 500). A flush starts as soon as this many are waiting. */ maxBatchSize?: number; /** Flushes whatever is waiting this often (default 5000 ms); 0 disables the timer. */ flushIntervalMs?: number; /** Most events held at once, sent or not (default 10 000). When full, a new event is dropped and reported `buffer_full`. */ maxQueueSize?: number; /** Flushes an event may fail in before it is dropped and reported `failed` (default 3). */ maxAttempts?: number; /** * Receives every event that leaves the buffer unsent, with the reason in `error.code`. Without it each is emitted * as a `NozleTrackingWarning` process warning. It must not throw; anything it throws is ignored. */ onError?: (error: EventBufferError, events: TrackBatchEvent[]) => void; } type SendBatch = (events: TrackBatchEvent[], options: TrackBatchOptions) => Promise; /** * Queues events in memory and sends them through `trackBatch()` in the background: when `maxBatchSize` are waiting, * every `flushIntervalMs`, and before the process exits. Create it with {@link Nozle.createEventBuffer}. */ declare class EventBuffer { private readonly sendBatch; private queue; private inFlight; private running?; private queued?; private closing?; private closed; private autoPending; private backoffMs; private pausedUntil; private exitTimer?; private readonly timer?; private readonly maxBatchSize; private readonly maxQueueSize; private readonly maxAttempts; private readonly onError?; private readonly onBeforeExit; constructor(sendBatch: SendBatch, options?: EventBufferOptions); /** Events waiting to be sent, not counting a request in flight. */ get size(): number; /** * Queues one event and returns its transaction ID (yours, or a generated UUID v7) at once, without a request. * Every resend carries that ID, so Engine records the event once. Throws `NozleValidationError` for an event * `trackBatch()` would refuse. A full or closed buffer drops the event and reports it to `onError` instead of throwing. */ track(event: TrackBatchEvent): string; /** * Sends every event waiting now and resolves when done; it never rejects. Events whose request failed go back to * the front of the queue for the next flush; rejected ones and those out of attempts are reported to `onError`. * Only one flush runs at a time: a call during a flush waits for it and then sends what is waiting. * It does not wait for the backoff that follows a flush with failures. It first waits for the LLM responses * that wrappers given this buffer are still reading, so their usage is sent too. */ flush(): Promise; private flushQueue; /** * Waits for the LLM responses that wrappers given this buffer are still reading, then stops the timer and the * exit hook, sends everything (retrying failures up to `maxAttempts`) and refuses later events. */ close(): Promise; /** A size, timer or exit trigger: skipped during a backoff, and run after the flush in progress. */ private autoFlush; private start; private send; private report; } /** The request a captured call was made with, for choosing the customer per request. */ interface CaptureRequest { url: string; method: string; headers: Headers; } interface CaptureFetchOptions { /** * The customer to bill. A function is called for every request, so one shared provider client * can bill the right customer. A request can also name its customer with the * `X-Nozle-Customer-Id` header, which wins and is not sent to the provider. */ customerId?: string | ((request: CaptureRequest) => string | undefined); /** Feature code of the usage event. Default `llm_tokens`. */ featureCode?: string; /** Stored as the `feature` property. The `X-Nozle-Feature` request header wins. */ feature?: string; /** Also send one cost event per token category to this cost meter. */ costMeterCode?: string; /** * Ask OpenAI-compatible chat streams to include usage (`stream_options.include_usage`), which * they otherwise leave out. Default true. Turn it off for a server that rejects the field. */ includeStreamUsage?: boolean; /** * Called when usage could not be read or recorded, and once per event code when no Feature has * that code (`code: "feature_not_found"`). Without it, failures are emitted as a `NozleTrackingWarning` * process warning. The provider response is never affected. */ onError?: (error: unknown) => void; /** * Queues each usage event in this buffer instead of sending it at once, so `await buffer.flush()` or * `buffer.close()` sends it; both first wait for responses still being read. Its delivery failures then go to * the buffer's `onError`. Cost events are still sent directly, and the buffer's `flush()` and `close()` wait for them. */ buffer?: EventBuffer; } /** * Returns a `fetch` that passes every request through unchanged and records the token usage of * each successful LLM response. Pass it to any client that accepts a custom `fetch`: the OpenAI * and Anthropic SDKs, the Vercel AI SDK providers, LangChain, or your own code. Usage is * recognised by the shape of the response, so any OpenAI-compatible API, Anthropic and Gemini * work without naming the provider. Streams are read in the background as the app reads them. */ declare function captureFetch(nozle: Nozle, options?: CaptureFetchOptions, fetchImpl?: typeof fetch): typeof fetch; declare class CreditsNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); getBalance(customerId: string, creditSystemCode: string): Promise; listBalances(customerId: string): Promise; listOperations(customerId: string, query?: CreditOperationQuery): Promise; getEntityBalance(customerId: string, entityId: string, creditSystemCode: string): Promise; listEntityBalances(customerId: string, entityId: string): Promise; /** Every credit operation of the customer, page after page. `query.cursor` sets where to start. */ iterateOperations(customerId: string, query?: CreditOperationQuery): AsyncGenerator; /** Every credit operation of the Entity, page after page. */ iterateEntityOperations(customerId: string, entityId: string, query?: CreditOperationQuery): AsyncGenerator; listEntityOperations(customerId: string, entityId: string, query?: CreditOperationQuery): Promise; allocate(customerId: string, entityId: string, params: EntityCreditTransferParams, options: IdempotentMutationOptions): Promise; deallocate(customerId: string, entityId: string, params: EntityCreditTransferParams, options: IdempotentMutationOptions): Promise; private transfer; private entityCreditBaseUrl; } declare class CostEventsNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); createCostEventId(): string; track(params: CostEventParams): Promise; } /** Ledger-backed cost reporting and Shared Period Cost allocation (Engine, secret keys). */ declare class CostIntelligenceNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); /** Cost totals, feature and customer breakdowns, ledger entries and the review queues for a period. */ report(params?: CostIntelligenceReportParams): Promise; /** The recognized amount and customer split of one pool's period, without writing anything. */ previewSharedCostAllocation(poolId: string, params: SharedCostAllocationParams): Promise; /** Books a closed period of one pool now (Nozle also does it within about 15 minutes of the close). Repeating it is safe. */ allocateSharedCost(poolId: string, params: SharedCostAllocationParams): Promise; private allocation; private requireSecretKey; } declare class CreditSystemsNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); list(): Promise; } declare class EntitiesNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); get(customerId: string, entityId: string): Promise; /** Every Entity of the customer, page after page. `query.cursor` sets where to start. */ iterate(customerId: string, query?: CustomerEntityListQuery): AsyncGenerator; list(customerId: string, query?: CustomerEntityListQuery): Promise; upsert(customerId: string, entityId: string, data: CustomerEntityUpsertData, options: IdempotentMutationOptions): Promise; suspend(customerId: string, entityId: string, options: IdempotentMutationOptions): Promise; activate(customerId: string, entityId: string, options: IdempotentMutationOptions): Promise; bulkUpsert(customerId: string, entities: CustomerEntityBulkUpsertItem[], options: IdempotentMutationOptions): Promise; private entityUrl; } declare class EntitySubscriptionsNamespace { private readonly coreUrl; private readonly apiKey; private readonly policy; constructor(coreUrl: string, apiKey: string, policy: RequestPolicy); ensure(customerId: string, entityId: string): Promise; get(customerId: string, entityId: string): Promise; list(customerId: string): Promise; checkout(customerId: string, entityId: string, params: EntitySubscriptionCheckoutParams): Promise; checkoutMany(customerId: string, params: EntitySubscriptionCheckoutManyParams): Promise; changePlan(customerId: string, entityId: string, params: EntitySubscriptionCheckoutParams): Promise; cancel(customerId: string, entityId: string, params: EntitySubscriptionCancelParams): Promise; remove(customerId: string, entityId: string): Promise; private change; private requestEntity; private validatePath; private requireSecret; private entityPath; } declare class EventsNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); createTransactionId(): string; /** * Voids a recorded usage event by transaction ID (`POST /events/{transaction_id}/void`, Engine). Idempotent: a * replay answers `status: "already_voided"`. Refusals throw `NozleApiError` with an {@link EventVoidErrorCode} * (`event_not_found` 404, `period_invoiced` 409, `reason_required` 422; `transaction_voided` 409 on a later `track`). * Retried like `track`, since a repeat has no further effect. */ void(transactionId: string, options: { reason: string; }): Promise; } declare class MarginClient { private readonly base; private readonly headers; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); private get; summary(params?: MarginQueryParams): Promise<{ total_revenue_cents: number; total_cost_cents: number; total_margin_cents: number; margin_percent: number; event_count: number; }>; byCustomer(params?: MarginQueryParams): Promise<{ customers: components["schemas"]["MarginCustomerRow"][] | null; }>; byMetric(params?: MarginQueryParams): Promise<{ metrics: components["schemas"]["MarginMetricRow"][] | null; }>; byPlan(params?: MarginQueryParams): Promise<{ plans: components["schemas"]["MarginPlanRow"][] | null; }>; byModel(params?: MarginQueryParams): Promise<{ models: components["schemas"]["MarginModelRow"][] | null; }>; trend(params?: TrendParams): Promise<{ granularity: string; trend: components["schemas"]["MarginTrendPoint"][] | null; }>; /** Replays one metric's recorded usage in the range at a new unit price; the recorded cost is kept. */ simulate(params: MarginSimulateParams, range?: MarginQueryParams): Promise; } type ProviderTokenType = "input" | "cached_input" | "cache_write" | "cache_write_1h" | "output" | "reasoning" | "audio_input" | "audio_output" | "image_input" | "image_output" | "batch_input" | "batch_output"; /** One call's usage. `categories` are the disjoint token buckets: every token sits in exactly one. */ interface ProviderTokenUsage { featureInputTokens: number; featureOutputTokens: number; categories: Array<{ type: ProviderTokenType; tokens: number; }>; /** `batch` when the whole call was billed at the provider's batch tier. */ serviceTier?: "batch"; /** `estimated` when Nozle counted the tokens itself (an aborted stream). Default `reported`. */ usageSource?: "reported" | "estimated"; /** The stream ended before the provider sent its final usage. */ streamAborted?: boolean; } /** Bytes per token for the estimate of an aborted stream. The same constant and rule in every Nozle SDK and the Engine. */ declare const ESTIMATE_BYTES_PER_TOKEN = 4; /** `ceil(bytes / 4)`. */ declare function estimateTokens(bytes: number): number; /** The usage format a response was recognised by: OpenAI-compatible, Anthropic, or Gemini. */ type ProviderUsageFormat = "openai" | "anthropic" | "gemini"; /** Token usage found in one provider response, with the response's own id and model. */ interface DetectedUsage { format: ProviderUsageFormat; usage: ProviderTokenUsage; id?: string; model?: string; } declare function normalizeOpenAIUsage(usage: any): ProviderTokenUsage; declare function normalizeAnthropicUsage(usage: any): ProviderTokenUsage; declare function normalizeGeminiUsage(usage: any): ProviderTokenUsage; /** * Recognises token usage by the shape of a provider response, not by provider name: an * OpenAI-style `usage` (`prompt_tokens`, or `input_tokens` from the Responses API), an * Anthropic `usage` (a `message` object or cache token fields), or Gemini `usageMetadata`. * Returns undefined when the body carries no usage. */ declare function detectUsage(body: any): DetectedUsage | undefined; /** Token usage your code read from a provider response, for clients `captureFetch` cannot wrap. */ interface RecordUsageParams { customerId: string; /** Feature code of the usage event. Default `llm_tokens`. */ featureCode?: string; model: string; /** All input tokens, including cached input and cache writes. */ inputTokens: number; /** All output tokens, including reasoning tokens. */ outputTokens: number; cachedInputTokens?: number; /** Cache writes at the default (5 minute) TTL. */ cacheWriteTokens?: number; /** Cache writes at the 1 hour TTL. */ cacheWrite1hTokens?: number; reasoningTokens?: number; audioInputTokens?: number; audioOutputTokens?: number; imageInputTokens?: number; imageOutputTokens?: number; /** `batch` when the call was billed at the provider's batch tier. */ serviceTier?: "batch" | "standard"; /** Stored as the `provider` property, for example `openai`. */ provider?: string; /** The provider's response id. Recording the same id twice records one event. */ requestId?: string; latencyMs?: number; feature?: string; costMeterCode?: string; } declare class UsageNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; /** * Holds: reserve credits (Engine 2.34.0+), or the estimated spend of a Feature billed in money under a hard spend * limit (a budget hold, `kind: "budget"`; Engine 2.34.0+), before a call whose final amount is known only afterwards. */ readonly holds: UsageHoldsNamespace; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); check(params: UsageCheckParams): Promise; private readonly generatedTimestamps; track(params: UsageTrackParams, options: UsageTrackOptions): Promise; } declare class UsageHoldsNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); private readonly generatedTimestamps; /** * Reserves the credits `usage.track` would spend, or for a Feature billed in money under a hard spend limit its * estimated spend (a budget hold). A short balance or a used-up limit answers `allowed: false`, not an error. */ create(params: UsageHoldCreateParams, options: UsageTrackOptions): Promise; /** * Spends the actual usage, priced at the rate pinned by the hold, and releases what is left. Engine replays a * repeated finalize with the same usage, so it is retried like an idempotent call. */ finalize(holdId: string, params?: UsageHoldFinalizeParams): Promise; /** Returns the held credits. Idempotent; a finalized hold throws `hold_already_resolved` (409). */ release(holdId: string): Promise; get(holdId: string): Promise; /** The customer's newest holds (at most 100), optionally of one status. */ list(customerId: string, options?: UsageHoldListOptions): Promise; private holdUrl; } /** Money budgets (spend limits) and their standing (Engine 2.34.0+). */ declare class BudgetsNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy); /** Every spend limit of the customer's subscription with its spend, open holds and status in the current period. */ list(customerId: string, options?: BudgetListOptions): Promise; } /** A verified webhook from Nozle. */ interface NozleWebhookEvent> { /** `webhook-id`: the same on every delivery attempt, so use it to skip duplicates. */ id: string; /** `webhook_type`, for example `subscription.started`. */ type: string; /** `object_type`, for example `subscription`. */ objectType: string; organizationId: string | null; /** The object the webhook is about: `payload[objectType]`. */ object: T; /** The whole parsed body. */ payload: Record; } type WebhookVerificationCode = "missing_signature" | "missing_secret" | "invalid_timestamp" | "invalid_signature" | "invalid_payload"; /** The request is not a genuine Nozle webhook. Answer it with 400 and do not act on it. */ declare class WebhookVerificationError extends Error { readonly code: WebhookVerificationCode; constructor(code: WebhookVerificationCode, message: string); } type WebhookHeaders = Headers | Record; interface VerifyWebhookInput { /** The raw request body, exactly as received. Parsed and re-serialised JSON fails the check. */ body: string | Uint8Array; headers: WebhookHeaders; /** The endpoint's `whsec_` secret. Pass several while a secret is being rotated. */ secret?: string | string[]; /** Largest accepted gap, in seconds, between `webhook-timestamp` and now. Default 300. */ toleranceSeconds?: number; } declare class WebhooksNamespace { /** * Checks `webhook-id`, `webhook-timestamp` and `webhook-signature` against the raw body and * returns the parsed event, or throws `WebhookVerificationError`. Local only: no network call. */ verify(input: VerifyWebhookInput): Promise; } interface WebhookHandlerOptions { /** The endpoint's `whsec_` secret, or several during rotation. */ secret?: string | string[]; /** Timestamp tolerance in seconds. Default 300. */ toleranceSeconds?: number; /** Called once per verified delivery. Throw to answer 500, so Nozle tries again. */ onEvent: (event: NozleWebhookEvent) => void | Promise; } /** * A Fetch API handler (Next.js route handlers, Remix, Hono, Bun, Deno) for Nozle webhooks: verifies * the signature, calls `onEvent`, and answers 200, 400 for a request that is not genuine, or 500 * when `onEvent` throws. */ declare function createWebhookHandler(nozle: { webhooks: WebhooksNamespace; }, options: WebhookHandlerOptions): (request: Request) => Promise; type CreditNote = components["schemas"]["CreditNoteObject"]; /** Why the credit note is issued. Core stores one of these; it defaults to `other`. */ type CreditNoteReason = "duplicated_charge" | "product_unsatisfactory" | "order_change" | "order_cancellation" | "fraudulent_charge" | "other"; /** One invoice fee, and how much of it (in cents, before tax) the credit note covers. */ interface CreditNoteItem { /** `fees[].nozle_id` of the invoice. */ feeId: string; amountCents: number; } interface PreviewCreditNoteParams { /** `nozle_id` of a finalized invoice. */ invoiceId: string; items: CreditNoteItem[]; } /** * What a credit note for these items would be worth, with taxes and coupons applied. Nothing is created. * `maxRefundableAmountCents` is what has been paid and not yet refunded, capped at the total. */ interface CreditNotePreview { invoice_id: string; invoice_number: string; currency: string; taxes_amount_cents: number; precise_taxes_amount_cents: string | number; taxes_rate: number; sub_total_excluding_taxes_amount_cents: number; max_creditable_amount_cents: number; max_refundable_amount_cents: number; /** Sent by newer Core versions only. */ max_offsettable_amount_cents?: number; coupons_adjustment_amount_cents: number; precise_coupons_adjustment_amount_cents: number; items: { fee_id: string | null; amount_cents: number; }[]; applied_taxes?: Record[]; } interface CreateCreditNoteParams extends PreviewCreditNoteParams { /** * How the credit note's total is settled. The three amounts must add up to the total of `items` * with taxes (take it from `preview()`); at least one must be above zero. * - `creditAmountCents`: added to the customer's balance, applied to their next invoice. * - `refundAmountCents`: returned to the customer's original payment method by the payment provider. * Only up to what was paid on the invoice and not refunded yet. Its `outOfBandRefundAmountCents` part is * recorded as already paid back by you and is not sent to a provider. * - `offsetAmountCents`: deducted from what the customer still owes on the invoice. */ creditAmountCents?: number; refundAmountCents?: number; offsetAmountCents?: number; /** * The part of `refundAmountCents` you already paid back yourself outside any payment provider (bank transfer, * cash). Nozle records it as refunded and never sends it to a provider. Use it for an invoice paid with a manual * payment, only marked paid, or paid through a provider Nozle cannot refund through. Core 11.46.0. */ outOfBandRefundAmountCents?: number; /** Your reference for the out-of-band refund, for example a bank transfer ID (up to 255 characters). */ outOfBandRefundReference?: string; /** ISO 8601 time you made the out-of-band refund; Core uses the creation time when left out. */ outOfBandRefundedAt?: string; reason?: CreditNoteReason; /** Printed on the credit note PDF. */ description?: string; /** Your own key-value pairs, for example your ticket number. Values are strings. */ metadata?: Record; } interface RefundParams extends PreviewCreditNoteParams { reason?: CreditNoteReason; description?: string; metadata?: Record; /** * When less was paid than the items are worth, refund what was paid and credit the rest to the customer's * balance. Without it `refund()` throws `refund_exceeds_paid_amount` and creates nothing. */ creditRemainder?: boolean; } interface ListCreditNotesOptions { /** Only this customer's credit notes. */ customerId?: string; invoiceNumber?: string; reason?: CreditNoteReason; creditStatus?: "available" | "consumed" | "voided"; refundStatus?: "pending" | "succeeded" | "failed"; currency?: string; /** Inclusive dates, `YYYY-MM-DD`. */ issuingDateFrom?: string; issuingDateTo?: string; amountFrom?: number; amountTo?: number; page?: number; perPage?: number; } interface CreditNotePage { credit_notes: CreditNote[]; meta: { current_page: number; next_page: number | null; prev_page: number | null; total_pages: number; total_count: number; }; } /** * Codes Core puts in `NozleApiError.code` or `errorDetails` for credit notes; test with `error.hasCode(...)`. * `refund_exceeds_paid_amount` is raised by this SDK's `refund()`, the rest by Core. */ declare const CREDIT_NOTE_ERROR_CODES: { /** Invoice is a draft, an old version, or an unpaid prepaid-credit invoice (HTTP 422). */ readonly invalidTypeOrStatus: "invalid_type_or_status"; /** `refundAmountCents` on an invoice nothing was paid on. */ readonly cannotRefundUnpaidInvoice: "cannot_refund_unpaid_invoice"; /** An amount is above what is left on the invoice (paid for refunds, creditable for credits). */ readonly higherThanRemainingInvoiceAmount: "higher_than_remaining_invoice_amount"; /** An item is above what is left of its fee. */ readonly higherThanRemainingFeeAmount: "higher_than_remaining_fee_amount"; /** credit + refund + offset do not add up to the items with taxes. */ readonly doesNotMatchItemAmounts: "does_not_match_item_amounts"; readonly totalAmountMustBePositive: "total_amount_must_be_positive"; /** Void of a credit note with nothing left to void (HTTP 422). */ readonly noVoidableAmount: "no_voidable_amount"; readonly refundExceedsPaidAmount: "refund_exceeds_paid_amount"; /** The online part of the refund needs a manual payment, or the invoice was only marked paid: use `outOfBandRefundAmountCents`. */ readonly manualRefundRequired: "manual_refund_required"; /** The invoice was paid through a provider Nozle cannot refund through: use `outOfBandRefundAmountCents`. */ readonly providerRefundUnsupported: "provider_refund_unsupported"; /** The invoice's provider payments still hold less than the online part of the refund. */ readonly insufficientRefundableAmount: "insufficient_refundable_amount"; /** `outOfBandRefundAmountCents` is above `refundAmountCents`. */ readonly higherThanRefundAmount: "higher_than_refund_amount"; }; declare class CreditNotesNamespace { private readonly coreUrl; private readonly apiKey; private readonly policy; constructor(coreUrl: string, apiKey: string, policy: RequestPolicy); /** What a credit note for these items would be worth. Creates nothing, so it is safe to retry. */ preview(params: PreviewCreditNoteParams): Promise; /** * Issues a credit note. It sends no `Idempotency-Key` yet, so the SDK never retries it: if it fails * with a network error or a 5xx, call `list({ customerId, invoiceNumber })` before trying again. * A refund is started with the payment provider after the call returns; follow `refund_status` * with `get()` or the `credit_note.refund_failure` webhook. Its out-of-band part is settled at once. */ create(params: CreateCreditNoteParams): Promise; /** * Refunds the items to the customer's original payment method: `preview()` for the exact total, then * `create()` with that total as `refundAmountCents`. Two calls, and the second is not retried. */ refund(params: RefundParams): Promise; /** Credit notes, newest first; all of them, or one customer's with `customerId`. */ list(options?: ListCreditNotesOptions): Promise; get(creditNoteId: string): Promise; /** * Voids what is left of the credit note's credit balance. It does not undo a refund that was paid out * or an offset already applied. Throws `no_voidable_amount` (422) when nothing is left. Never retried. */ void(creditNoteId: string): Promise; private call; } type Schemas = components["schemas"]; /** Who computes tax for a billing entity: `nozle` (taxes and EU VAT rules) or `stripe_tax`. */ type BillingEntityTaxProvider = "nozle" | "stripe_tax"; /** Fields Core adds to a billing entity for Stripe Tax; older Cores leave them out. */ interface BillingEntityTaxFields { tax_provider?: BillingEntityTaxProvider; /** Stripe product tax code, for example `txcd_10000000`; used when `tax_provider` is `stripe_tax`. */ provider_tax_code?: string | null; customer_location_required?: boolean; einvoicing?: boolean; } type BillingEntity = Schemas["BillingEntityObject"] & BillingEntityTaxFields; /** What `get` and `update` return: the entity with its applied `taxes` and `selected_invoice_custom_sections`. */ type BillingEntityDetails = Schemas["BillingEntityObjectExtended"] & BillingEntityTaxFields; /** Core's `billing_configuration`, camelCase. */ interface BillingEntityConfiguration { invoiceFooter?: string; invoiceGracePeriod?: number; subscriptionInvoiceIssuingDateAnchor?: "current_period_end" | "next_period_start"; subscriptionInvoiceIssuingDateAdjustment?: "align_with_finalization_date" | "keep_anchor"; documentLocale?: string; } interface UpdateBillingEntityParams { name?: string; einvoicing?: boolean; email?: string; legalName?: string; legalNumber?: string; taxIdentificationNumber?: string; addressLine1?: string; addressLine2?: string; city?: string; state?: string; zipcode?: string; /** ISO 3166-1 alpha-2, for example `DE`. */ country?: string; defaultCurrency?: string; timezone?: string; documentNumbering?: "per_customer" | "per_billing_entity"; documentNumberPrefix?: string; finalizeZeroAmountInvoice?: boolean; netPaymentTerm?: number; /** Cannot be on together with `taxProvider: "stripe_tax"`; Core answers 422. */ euTaxManagement?: boolean; customerLocationRequired?: boolean; taxProvider?: BillingEntityTaxProvider; providerTaxCode?: string; emailSettings?: string[]; billingConfiguration?: BillingEntityConfiguration; } interface CreateBillingEntityParams extends UpdateBillingEntityParams { code: string; name: string; } /** `update` only: replace the applied taxes and invoice custom sections by code. */ interface UpdateBillingEntityAppliedParams extends UpdateBillingEntityParams { taxCodes?: string[]; invoiceCustomSectionCodes?: string[]; } /** Billing entities: the legal entities that issue invoices, including their tax provider (`nozle` or `stripe_tax`). */ declare class BillingEntitiesNamespace { private readonly coreUrl; private readonly apiKey; private readonly policy; constructor(coreUrl: string, apiKey: string, policy: RequestPolicy); list(): Promise; get(code: string): Promise; /** Creates an entity. It sends no `Idempotency-Key`, so it is never retried; a duplicate `code` answers 422. */ create(params: CreateBillingEntityParams): Promise; /** Changes the given fields only. Switching to `taxProvider: "stripe_tax"` needs `euTaxManagement` off. Never retried. */ update(code: string, params: UpdateBillingEntityAppliedParams): Promise; private path; private call; } /** An invoice; `tax_status`, `tax_treatment` and `tax_details` come from Cores that support customer tax data. */ type Invoice = components["schemas"]["InvoiceObject"] & InvoiceTaxFields; interface InvoicePage { invoices: Invoice[]; meta: { current_page: number; next_page: number | null; prev_page: number | null; total_pages: number; total_count: number; }; } interface ListInvoicesOptions { /** `draft`, `finalized`, `voided`, `failed` or `pending`. */ status?: string; /** `pending`, `succeeded` or `failed`. */ paymentStatus?: string; /** Only invoices past their due date and not paid (`true`), or only the others (`false`). */ paymentOverdue?: boolean; /** Inclusive dates, `YYYY-MM-DD`. */ issuingDateFrom?: string; issuingDateTo?: string; page?: number; perPage?: number; } /** * Why Core refused `invoices.payWithAgentToken`. 422 codes arrive in `errorDetails.agent_payment_token` (the limit codes * and `invalid_format`), `stripe_required` in `errorDetails.payment_provider`; `feature_not_enabled` is a 403 and * `invoice_not_payable` a 422 `code`. Test with `error.hasCode(...)`. */ declare const AgentTokenErrorCode: { readonly FeatureNotEnabled: "feature_not_enabled"; readonly InvalidFormat: "invalid_format"; readonly InvoiceNotPayable: "invoice_not_payable"; readonly StripeRequired: "stripe_required"; readonly TokenDeactivated: "token_deactivated"; readonly TokenExpired: "token_expired"; readonly CurrencyMismatch: "currency_mismatch"; readonly AmountExceedsLimit: "amount_exceeds_limit"; }; type AgentTokenErrorCode = (typeof AgentTokenErrorCode)[keyof typeof AgentTokenErrorCode]; /** * Why Core refused `invoices.getX402Requirements` or `invoices.payWithX402`. `feature_not_enabled` is a 403, * `invoice_not_payable` a 422 `code`; `usd_required` arrives in `errorDetails.currency`, `stripe_required` in * `errorDetails.payment_provider` and `invalid_format` in `errorDetails.transaction_hash`. Test with `error.hasCode(...)`. */ declare const X402ErrorCode: { readonly FeatureNotEnabled: "feature_not_enabled"; readonly InvoiceNotPayable: "invoice_not_payable"; readonly UsdRequired: "usd_required"; readonly StripeRequired: "stripe_required"; readonly InvalidFormat: "invalid_format"; }; type X402ErrorCode = (typeof X402ErrorCode)[keyof typeof X402ErrorCode]; /** x402 payment requirements for an invoice (`x402Version` 2); `accepts` and `resource` are passed through from Core. */ interface X402Requirements { x402Version: number; accepts: Record[]; resource?: Record; [key: string]: unknown; } declare class InvoicesNamespace { private readonly coreUrl; private readonly apiKey; private readonly policy; constructor(coreUrl: string, apiKey: string, policy: RequestPolicy); /** A customer's invoices, newest first. */ list(customerId: string, options?: ListInvoicesOptions): Promise; get(invoiceId: string): Promise; /** * The PDF's URL. A finalized invoice whose PDF does not exist yet returns `null`: Core starts * generating it, so ask again shortly (or wait for the `invoice.generated` webhook). */ downloadUrl(invoiceId: string): Promise; /** * Pays a finalized invoice with a Stripe Shared Payment Token (`spt_...`) an AI agent handed you. Returns the invoice * with its new payment status; a declined charge is a 200 with a failed payment, not an error. Needs the * `stripe_agent_payment_token` feature flag on your organization and a Stripe-connected customer. Refusals are * `NozleApiError`s; see {@link AgentTokenErrorCode}. Never retried: it moves money. */ payWithAgentToken(invoiceId: string, agentPaymentToken: string): Promise; /** * What an x402 payer must send to settle this invoice (USDC on Base to the merchant's Stripe deposit address). Needs the * `stripe_x402_payments` feature flag, a USD invoice and a Stripe-connected customer. Refusals are `NozleApiError`s; * see {@link X402ErrorCode}. Safe to retry. */ getX402Requirements(invoiceId: string): Promise; /** * Records an x402 payment the payer already settled on-chain: pass the transaction hash (`0x` + 64 hex). Returns the * invoice; the payment is often `processing` first and the Stripe webhook finishes it. Core treats the hash as the * idempotency key, but the SDK never retries it on its own: it moves money. Refusals are `NozleApiError`s; see * {@link X402ErrorCode}. */ payWithX402(invoiceId: string, transactionHash: string): Promise; private raw; private call; } /** Usage alerts belong to a subscription; balance alerts to one of the customer's wallets. */ type AlertTarget = { subscriptionId: string; } | { customerId: string; walletCode: string; }; type AlertType = "current_usage_amount" | "feature_current_usage_amount" | "feature_current_usage_units" | "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance"; interface AlertThreshold { /** Amount in cents, units, or credits, by alert type. */ value: string | number; code?: string | null; /** Fires again every `value` past the last threshold. At most one per alert. */ recurring?: boolean; } interface Alert { nozle_id: string; alert_type: AlertType; code: string; name: string | null; external_subscription_id: string | null; wallet_code: string | null; direction: "increasing" | "decreasing"; previous_value: string | number | null; last_processed_at: string | null; thresholds: { code: string | null; value: string; recurring: boolean; }[]; feature: { code: string; name: string; } | null; created_at: string; } interface CreateAlertInput { alertType: AlertType; code: string; name?: string; /** Required for the feature_* types. */ featureCode?: string; thresholds: AlertThreshold[]; } type UpdateAlertInput = Partial>; declare class AlertsNamespace { private readonly coreUrl; private readonly apiKey; private readonly policy; constructor(coreUrl: string, apiKey: string, policy: RequestPolicy); list(target: AlertTarget, options?: { page?: number; perPage?: number; }): Promise<{ alerts: Alert[]; meta: Record; }>; get(target: AlertTarget, code: string): Promise; /** Nozle sends the `alert.triggered` webhook when a threshold is crossed. */ create(target: AlertTarget, input: CreateAlertInput): Promise; /** Thresholds, when given, replace the existing ones. */ update(target: AlertTarget, code: string, input: UpdateAlertInput): Promise; delete(target: AlertTarget, code: string): Promise; private fields; private base; private one; private call; } /** * One version of a plan code. A plan is version 1 until its pricing is changed while customers pay for it; that * change saves version 2, and so on. Subscriptions stay on their version until a version migration moves them. */ interface PlanVersion { nozle_id: string; version: number; is_current: boolean; created_at: string; amount_cents: number; amount_currency: string; active_subscriptions_count: number; } /** The version whose subscriptions move, and the version they move to (the current version when omitted). */ interface PlanVersionMigrationInput { fromVersion: number; toVersion?: number; } type PlanVersionMigrationStatus = "running" | "succeeded" | "completed_with_errors" | "failed" | "canceled"; type PlanVersionMigrationSkipReason = "already_on_version" | "canceling" | "custom_pricing" | "different_billing" | "external_billing" | "in_trial" | "not_active" | "open_checkout" | "pending_plan_change"; /** What a migration did to one subscription. `move_status` says where a scheduled move stands. */ interface PlanVersionMigrationItem { external_subscription_id: string; status: "succeeded" | "skipped" | "failed" | "canceled"; skip_reason?: PlanVersionMigrationSkipReason | null; error?: string | null; effective_at?: string | null; move_status?: "pending" | "moved" | "canceled" | null; } interface PlanVersionMigration { nozle_id: string; plan_code: string; from_version: number; to_version: number; status: PlanVersionMigrationStatus; matched_count: number; succeeded_count: number; skipped_count: number; failed_count: number; started_at?: string | null; finished_at?: string | null; canceled_at?: string | null; created_at: string; /** Only from `getMigration`. */ items?: PlanVersionMigrationItem[]; } interface PlanVersionMigrationPreviewItem { external_subscription_id: string; external_customer_id?: string; outcome: "move" | "skip"; skip_reason?: string | null; effective_on?: string | null; current_amount_cents?: number; new_amount_cents?: number; } interface PlanVersionMigrationPreview { plan_code: string; from_version: number; to_version: number; items: PlanVersionMigrationPreviewItem[]; } /** The versions of a plan code and the migrations that move subscribers between them. Secret keys only. */ declare class PlanVersionsNamespace { private readonly coreUrl; private readonly apiKey; private readonly policy; constructor(coreUrl: string, apiKey: string, policy: RequestPolicy); /** Every version of the plan code, oldest first, with its price and active subscriptions. */ list(code: string): Promise; /** One version of the plan code, for example the older version a subscriber is billed on. */ get>(code: string, version: number): Promise; /** What migrating `fromVersion`'s subscriptions would do to each of them. Nothing is written. */ previewMigration(code: string, input: PlanVersionMigrationInput): Promise; /** * Starts moving `fromVersion`'s active subscriptions to `toVersion` (the current version by default). Each moves * at the end of its billing period; nothing is invoiced or refunded now. The migration runs in the background: * read it again with `getMigration`. Another migration of the code still running fails with a 409 * `plan_version_migration_running`. */ createMigration(code: string, input: PlanVersionMigrationInput): Promise; /** The migrations of the plan code, newest first, without their items. */ listMigrations(code: string): Promise; /** A migration with what it did to each subscription. */ getMigration(code: string, id: string): Promise; /** Stops a migration and unschedules every move not started; those subscriptions stay on their version. */ cancelMigration(code: string, id: string): Promise; private plan; private migrations; private one; private migration; private call; } declare class Nozle { readonly apiKey: string; readonly baseUrl: string; readonly eventsUrl: string; readonly margin: MarginClient; readonly events: EventsNamespace; readonly costEvents: CostEventsNamespace; /** Ledger-backed cost report and Shared Period Cost allocation (secret keys). */ readonly costIntelligence: CostIntelligenceNamespace; readonly customers: CustomersNamespace; readonly creditSystems: CreditSystemsNamespace; readonly entities: EntitiesNamespace; readonly entitySubscriptions: EntitySubscriptionsNamespace; readonly credits: CreditsNamespace; readonly usage: UsageNamespace; /** Money budgets: `list(customerId, { subscriptionId })` (Engine 2.34.0+). */ readonly budgets: BudgetsNamespace; /** Verifies webhooks Nozle sends to your endpoint. */ readonly webhooks: WebhooksNamespace; /** A customer's invoices and their PDFs. */ readonly invoices: InvoicesNamespace; /** Preview, issue, refund, list and void credit notes. Needs a secret key. */ readonly creditNotes: CreditNotesNamespace; readonly billingEntities: BillingEntitiesNamespace; /** Usage and wallet-balance alerts; Nozle sends `alert.triggered` when one fires. */ readonly alerts: AlertsNamespace; /** The versions of a plan code and the migrations that move subscribers between them (secret keys). */ readonly planVersions: PlanVersionsNamespace; private readonly policy; private subCache; constructor(config?: NozleConfig); /** * Records many events through Engine's `/events/batch`: split into gzipped requests of `chunkSize` (at most 5000), * sent `concurrency` at a time. Returns one result per event and rejects only for invalid arguments; * a failed request marks its events `failed` and the other requests still run. See the README. */ trackBatch(events: TrackBatchEvent[], options?: TrackBatchOptions): Promise; /** * An in-memory queue that sends events through {@link Nozle.trackBatch} in the background: on size, on a timer and * before the process exits. Serverless handlers must `await buffer.flush()` or `buffer.close()` before returning. */ createEventBuffer(options?: EventBufferOptions): EventBuffer; track(customerId: string, event: string, metadata?: Record, options?: TrackOptions): Promise; can(customerId: string, feature: string, metadata?: Record, options?: CanOptions): Promise; /** * Current plan versions. A secret key gets every plan, including families hidden from the * pricing table; `includeHidden: false` gets the pricing table view a publishable key gets. * Without `currency` a secret key gets every plan in every currency; `currency` keeps that currency only, and * `externalCustomerId` the customer's locked currency (ignored when the organization allows several currencies per * customer). A publishable key without `currency` gets each family's default-currency plans. */ plans(options?: PlansOptions): Promise; /** `plan` is a plan code, or a family, interval and optional currency for Core to resolve to the plan. */ checkout(customerId: string, plan: string | PlanFamilySelection, returnUrl?: string, options?: CheckoutOptions): Promise; /** `returnUrl` is where the hosted payment page sends the customer after paying; without it the provider's own page is shown. */ checkoutInvoice(invoiceId: string, options?: CheckoutOptions & { returnUrl?: string; }): Promise; managePaymentMethod(customerId: string, returnUrl?: string, options?: Pick): Promise; verifyCheckout(checkoutId: string, verification: RazorpayVerification, scope?: SubscriptionCheckoutScope): Promise; /** * Status of a paid upgrade (pass its `plan_upgrade_intent_id` with the customer and subscription scope) or of a * Razorpay operation. Not a Stripe `checkout_id` (`cs_...`): a new-subscription or invoice Stripe checkout has no * status call, so confirm it through webhooks or by reloading billing state. */ checkoutStatus(checkoutId: string, scope?: SubscriptionCheckoutScope): Promise; private checkoutScopeQuery; subscriptionOptions(customerId: string, subscriptionId: string): Promise; previewSubscriptionChange(customerId: string, subscriptionId: string, planCode: string): Promise; withdrawPendingSubscriptionChange(customerId: string, subscriptionId: string, pendingSubscriptionId: string, idempotencyKey: string): Promise; private subscriptionManagementRequest; private checkoutRequest; /** * Subscribes the customer to the current version of the plan, or to `options.planVersion` (for example to keep * selling an older price). The same customer and code again keep the subscription's own version. `plan` may be a * family, interval and optional currency instead of a plan code. */ subscribe(customerId: string, plan: string | PlanFamilySelection, options?: SubscribeOptions): Promise; cancelSubscription(customerId: string, subscriptionId: string, policyOrOptions?: CancellationPolicy | CancelSubscriptionOptions): Promise; /** * Changes a subscription's trial (`PUT /subscriptions/{id}`, Core). `trial` has exactly one of `extend_days` * (adds to the current end), `ends_at` (absolute new end, at least 30 minutes ahead) or `convert: true` (ends the * trial now and starts paid billing); `reason` is optional (up to 500 characters). Refusals throw `NozleApiError` * with a {@link TrialErrorCode}. Not retried: a repeated extension would add twice. */ updateSubscription(externalId: string, update: { trial: SubscriptionTrialUpdate; }): Promise; /** Extends a trial by `days`, or moves its end to `endsAt` (ISO 8601). Give one of them. See {@link updateSubscription}. */ extendTrial(externalId: string, options: { days?: number; endsAt?: string; reason?: string; }): Promise; /** Ends a trial now and starts paid billing per the plan's rules. See {@link updateSubscription}. */ convertTrial(externalId: string, options?: { reason?: string; }): Promise; previewSubscriptionTransition(params: SubscriptionTransitionParams): Promise; applySubscriptionTransition(params: SubscriptionTransitionParams, idempotencyKey: string): Promise; private validateSubscriptionTransition; private subscriptionTransitionBody; /** * Returns a `fetch` that records the token usage of every LLM response it sees. Pass it as the * `fetch` option of the OpenAI or Anthropic SDK, a Vercel AI SDK provider, LangChain, or any * client that accepts one. See {@link CaptureFetchOptions}. */ captureFetch(options?: CaptureFetchOptions, fetchImpl?: typeof fetch): typeof fetch; /** Records one LLM call's token usage that your code read itself. */ recordUsage(params: RecordUsageParams): Promise; ping(): Promise; /** * Legacy wallet adapter: deducts `credits` from the customer's wallet. * * @deprecated Use {@link Nozle.usage}`.check()` and `.track()` with a credit system, which keep * metric conversion, source ordering, idempotency and the credit ledger authoritative. */ checkAndDeduct(params: CheckAndDeductParams): Promise; /** The customer's active subscriptions, from Core. */ getSubscriptions(customerId: string): Promise; /** Usage of the current billing period. Without `subscriptionId`, the one active subscription is used. */ currentUsage(customerId: string, options?: { subscriptionId?: string; }): Promise; /** Usage of past billing periods, newest first. `periods` limits how many (Core default otherwise). */ pastUsage(customerId: string, options?: { subscriptionId?: string; periods?: number; }): Promise; private resolveSubscription; } declare class CustomersNamespace { private readonly baseUrl; private readonly apiKey; private readonly policy; private readonly engineUrl; constructor(baseUrl: string, apiKey: string, policy: RequestPolicy, engineUrl: string); /** * Records the opening credit balance of a subscription imported with {@link importBillingState}, * without an invoice or a usage event (Engine). Retry an uncertain call with the same key and body. */ importCreditBalance(customerId: string, params: CreditBalanceImportParams, options: ImportOptions): Promise; /** * Imports a subscription another system already bills (`billing_authority: external`), without an * invoice, checkout or payment (Core). Retry an uncertain call with the same key and body. */ importBillingState(customerId: string, params: BillingStateImportParams, options: ImportOptions): Promise; private importRequest; upsert(params: CustomerUpsertParams): Promise; /** One customer with its tax fields (`tax_identification_status`, `tax_treatment`). Secret key. */ get(externalId: string): Promise; /** * Erases the customer's personal data (GDPR), irreversibly: Core sets `erased_at` and finishes in the background. * Refused with 422 while the customer has active subscriptions or draft or unpaid invoices * ({@link CustomerEraseErrorCode} in `errorDetails.customer`). Erasing an erased customer changes nothing. Secret key. */ erase(externalId: string): Promise; /** * Deletes the customer and ends its subscriptions. Not an erasure: the customer's personal data stays; use * {@link erase} for that. Secret key. */ delete(externalId: string): Promise; private write; /** * Polls `get` until `tax_identification_status` is not `pending` (a VIES check is running), then returns the * customer. Call it before a checkout so the price already reflects reverse charge. Throws after `timeoutMs` * (default 10 000) with the last customer unchanged on Core's side; the check keeps running. */ waitForTaxCheck(externalId: string, opts?: { timeoutMs?: number; intervalMs?: number; }): Promise; } /** A page with the cursor of the next one; `next_cursor` is null on the last page. */ type CursorPage = { next_cursor: string | null; }; /** * Yields every item of a cursor-paginated list, fetching the next page when the previous one is used up. * `fetchPage` gets the cursor (`start` for the first page) and `items` picks the page's rows. */ declare function paginate(fetchPage: (cursor: string | undefined) => Promise, items: (page: Page) => Item[], start?: string): AsyncGenerator; declare function createTransactionId(): string; declare function createCostEventId(): string; interface WrapOptions { customerId: string; metricCode?: string; feature?: string; costMeterCode?: string; /** Receives recording failures and a missing Feature for `metricCode`. Without it recording failures are emitted as a `NozleTrackingWarning` process warning. */ onError?: (error: unknown) => void; /** * Queues each usage event in this buffer instead of sending it at once, so `await buffer.flush()` or * `buffer.close()` sends it. Its delivery failures then go to the buffer's `onError`. Cost events are still * sent directly, and the buffer's `flush()` and `close()` wait for them. */ buffer?: EventBuffer; } declare function wrapOpenAI(client: T, nozle: Nozle, opts: WrapOptions): T; declare function wrapAnthropic(client: T, nozle: Nozle, opts: WrapOptions): T; interface BillingHandlerOptions { /** * The signed-in customer's Nozle external id, read from your own session or auth. Never take * it from the request query or body. Return null or undefined when no one is signed in; the * handler then answers 401. */ getCustomerId(request: Request): string | null | undefined | Promise; } /** The route names a billing handler serves, as the last segment of the request path. */ declare const BILLING_ROUTES: string[]; /** * A web-standard request handler that serves the `@nozle-js/react` billing hooks from your * backend with your secret key. Mount it under one path, for example `/api/nozle/[route]` in a * Next.js App Router route (`export const GET = handler`), Hono, Remix, Bun or Deno; the last * path segment picks the route. The customer always comes from `getCustomerId`, so a browser can * only read the signed-in customer's own billing data. */ declare function createBillingHandler(nozle: Nozle, options: BillingHandlerOptions): (request: Request) => Promise; export { AgentTokenErrorCode, type Alert, type AlertTarget, type AlertThreshold, type AlertType, AlertsNamespace, BILLING_ROUTES, BillingEntitiesNamespace, type BillingEntity, type BillingEntityConfiguration, type BillingEntityDetails, type BillingEntityTaxFields, type BillingEntityTaxProvider, type BillingHandlerOptions, type BillingStateImport, type BillingStateImportParams, type Budget, BudgetExceededError, type BudgetList, type BudgetListOptions, type BudgetUsageHold, type BudgetUsageHoldCreateResult, BudgetsNamespace, CREDIT_NOTE_ERROR_CODES, CUSTOMER_PAYMENT_OVERDUE, type CanOptions, type CanResult, type CancelSubscriptionOptions, type CancelSubscriptionResult, type CancellationPolicy, type CaptureFetchOptions, type CaptureRequest, type CheckAndDeductParams, type CheckAndDeductResult, type CheckoutOptions, type CheckoutResult, type CheckoutStatus, type CompletedCheckoutResult, type CoreSubscription, type CostEventAccepted, type CostEventParams, CostEventsNamespace, CostIntelligenceNamespace, type CostIntelligenceReport, type CostIntelligenceReportParams, type CreateAlertInput, type CreateBillingEntityParams, type CreateCreditNoteParams, type CreditBalance, type CreditBalanceImport, type CreditBalanceImportParams, type CreditBalanceSource, type CreditBalances, type CreditNote, type CreditNoteItem, type CreditNotePage, type CreditNotePreview, type CreditNoteReason, CreditNotesNamespace, type CreditOperation, type CreditOperationAllocation, type CreditOperationPage, type CreditOperationQuery, type CreditSystem, CreditSystemsNamespace, type CreditUsageHold, type CreditUsageHoldCreateResult, type CreditUsageHoldFinalizeResult, CreditsNamespace, type CustomerAddress, type CustomerBillingConfiguration, type CustomerEntity, type CustomerEntityBulkMutationCounts, type CustomerEntityBulkMutationResult, type CustomerEntityBulkUpsertItem, type CustomerEntityListQuery, type CustomerEntityMutationResult, type CustomerEntityPage, type CustomerEntityStatus, type CustomerEntityUpsertData, CustomerEraseErrorCode, CustomerTaxErrorCode, type CustomerTaxFields, type CustomerTaxId, type CustomerType, type CustomerUpsertParams, type CustomerUpsertResult, type CustomerUsage, type DetectedUsage, ESTIMATE_BYTES_PER_TOKEN, EntitiesNamespace, type EntityCreditBalance, type EntityCreditBalances, type EntityCreditOperationPage, type EntityCreditPoolPolicy, type EntityCreditTransferParams, type EntityCreditTransferResult, type EntityCreditTransferSource, type EntitySubscription, type EntitySubscriptionCancelParams, type EntitySubscriptionCancelResult, type EntitySubscriptionCheckoutItem, type EntitySubscriptionCheckoutItemResult, type EntitySubscriptionCheckoutManyParams, type EntitySubscriptionCheckoutManyResult, type EntitySubscriptionCheckoutParams, type EntitySubscriptionList, type EntitySubscriptionPlan, EntitySubscriptionsNamespace, type EventBatchErrorDetails, type EventBatchResponse, EventBuffer, EventBufferError, type EventBufferErrorCode, type EventBufferOptions, type EventVoid, type EventVoidEffects, EventVoidErrorCode, type EventVoidResult, EventsNamespace, type HostedCheckoutResult, type IdempotentMutationOptions, type ImportOptions, type Invoice, type InvoicePage, type InvoiceTaxDetails, type InvoiceTaxFields, InvoicesNamespace, type ListCreditNotesOptions, type ListInvoicesOptions, type ManagePaymentMethodResult, type MarginByCustomer, type MarginByMetric, type MarginByModel, type MarginByPlan, MarginClient, type MarginQueryParams, type MarginSimulateParams, type MarginSimulation, type MarginSummary, type MarginTrend, NO_ACTIVE_SUBSCRIPTION, Nozle, NozleApiError, type NozleConfig, NozleValidationError, type NozleWebhookEvent, type PingResult, type Plan, type PlanFamilyRef, type PlanFamilySelection, type PlanPrice, type PlanStatus, type PlanVersion, type PlanVersionMigration, type PlanVersionMigrationInput, type PlanVersionMigrationItem, type PlanVersionMigrationPreview, type PlanVersionMigrationPreviewItem, type PlanVersionMigrationSkipReason, type PlanVersionMigrationStatus, PlanVersionsNamespace, type PlansOptions, type PreviewCreditNoteParams, type ProcessingCheckoutResult, type ProviderTokenType, type ProviderTokenUsage, type ProviderUsageFormat, type RazorpayCheckoutResult, type RazorpayVerification, type RecordUsageParams, type RefundParams, RefusalReason, type ScheduledCheckoutResult, type SharedCostAllocationParams, type SharedCostAllocationPreview, type SharedCostAllocationRun, type SubscribeOptions, type SubscribeResult, type SubscriptionChangePreview, type SubscriptionCheckoutScope, type SubscriptionOptions, type SubscriptionPlan, type SubscriptionTransitionBillingAnchor, type SubscriptionTransitionCreditAction, type SubscriptionTransitionFinalInvoiceAction, type SubscriptionTransitionOperation, type SubscriptionTransitionParams, type SubscriptionTransitionPreview, type SubscriptionTransitionProrationBehavior, type SubscriptionTransitionRefundMode, type SubscriptionTransitionResult, type SubscriptionTransitionTiming, type SubscriptionTrialUpdate, TAX_ID_TYPES, type TaxIdStatus, type TaxIdType, type TaxTreatment, type TrackBatchEvent, type TrackBatchEventResult, type TrackBatchOptions, type TrackBatchResult, type TrackOptions, type TrendParams, TrialErrorCode, type UpdateAlertInput, type UpdateBillingEntityAppliedParams, type UpdateBillingEntityParams, type UpdateSubscriptionResult, type UsageCheckParams, type UsageCheckResult, type UsageDeduction, type UsageHold, type UsageHoldCreateParams, type UsageHoldCreateResult, type UsageHoldFinalizeParams, type UsageHoldFinalizeResult, type UsageHoldList, type UsageHoldListOptions, type UsageHoldStatus, UsageHoldsNamespace, UsageLimitExceededError, UsageNamespace, type UsageTrackOptions, type UsageTrackParams, type UsageTrackResult, type VerifyWebhookInput, type WebhookHandlerOptions, type WebhookHeaders, type WebhookVerificationCode, WebhookVerificationError, WebhooksNamespace, type WithdrawPendingSubscriptionChangeResult, type WrapOptions, X402ErrorCode, type X402Requirements, captureFetch, createBillingHandler, createCostEventId, createTransactionId, createWebhookHandler, detectUsage, estimateTokens, isCustomerPaymentOverdue, isNoActiveSubscription, normalizeAnthropicUsage, normalizeGeminiUsage, normalizeOpenAIUsage, paginate, refusedEventIndexes, wrapAnthropic, wrapOpenAI };