@paygentic/sdk 0.9.10 → 0.9.12

package/src/models/invoice.ts

@@ -64,7 +64,7 @@ export const PdfSource = {
 export type PdfSource = ClosedEnum<typeof PdfSource>;
 
 /**
- * Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `tax_provider` or null, and never `paygentic`. Use it to tell a withheld document apart from an invoice the tax provider serves by design — both report pdfSource `tax_provider`, but only a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.
+ * Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `null`, and never `paygentic`: an invoice whose document is withheld is not served the provider's in its place, because recording that link would mark the invoice as already served and stop a later repair rendering ours. Use it to tell a withheld invoice apart from one that simply has no document yet — both report pdfSource `null`, and only a withheld one names why. An invoice the tax provider serves by design reports pdfSource `tax_provider` with no reason, and needs no repair. Both an invoice with no document and a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.
  */
 export const DocumentWithheldReason = {
   TaxUnreconciled: "tax_unreconciled",
@@ -74,7 +74,7 @@ export const DocumentWithheldReason = {
   TaxProviderDisagrees: "tax_provider_disagrees",
 } as const;
 /**
- * Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `tax_provider` or null, and never `paygentic`. Use it to tell a withheld document apart from an invoice the tax provider serves by design — both report pdfSource `tax_provider`, but only a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.
+ * Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `null`, and never `paygentic`: an invoice whose document is withheld is not served the provider's in its place, because recording that link would mark the invoice as already served and stop a later repair rendering ours. Use it to tell a withheld invoice apart from one that simply has no document yet — both report pdfSource `null`, and only a withheld one names why. An invoice the tax provider serves by design reports pdfSource `tax_provider` with no reason, and needs no repair. Both an invoice with no document and a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.
  */
 export type DocumentWithheldReason = OpenEnum<typeof DocumentWithheldReason>;
 
@@ -227,7 +227,7 @@ export type Invoice = {
    */
   pdfSource?: PdfSource | null | undefined;
   /**
-   * Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `tax_provider` or null, and never `paygentic`. Use it to tell a withheld document apart from an invoice the tax provider serves by design — both report pdfSource `tax_provider`, but only a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.
+   * Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `null`, and never `paygentic`: an invoice whose document is withheld is not served the provider's in its place, because recording that link would mark the invoice as already served and stop a later repair rendering ours. Use it to tell a withheld invoice apart from one that simply has no document yet — both report pdfSource `null`, and only a withheld one names why. An invoice the tax provider serves by design reports pdfSource `tax_provider` with no reason, and needs no repair. Both an invoice with no document and a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.
    */
   documentWithheldReason?: DocumentWithheldReason | null | undefined;
   /**

package/src/models/invoicecategorysummary.ts

@@ -13,7 +13,7 @@ export type InvoiceCategorySummary = {
    */
   count: number;
   /**
-   * Total amount of invoices in this category in dollars
+   * Total amount of invoices in this category in dollars, including tax
    */
   amount: string;
 };

package/src/models/operations/createbillablemetric.ts

@@ -56,9 +56,9 @@ export type CreateBillableMetricRequest = {
   /**
    * CloudEvents type for meter routing. Links this billable metric to the metering service.
    */
-  eventType?: string | undefined;
+  eventType: string;
   /**
-   * JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`). Required for SUM/AVG/MIN/MAX/LATEST aggregations.
+   * JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`). Required for SUM/AVG/MIN/MAX/LATEST aggregations. Optional for UNIQUE_COUNT, which counts distinct values of this property when set and distinct events when not. Not stored for COUNT.
    */
   valueProperty?: string | undefined;
   /**
@@ -85,7 +85,7 @@ export type CreateBillableMetricRequest$Outbound = {
   productId?: string | undefined;
   itemId?: string | undefined;
   unit: string;
-  eventType?: string | undefined;
+  eventType: string;
   valueProperty?: string | undefined;
   groupBy?: { [k: string]: string } | undefined;
   eventFrom?: string | undefined;
@@ -104,7 +104,7 @@ export const CreateBillableMetricRequest$outboundSchema: z.ZodType<
   productId: z.string().optional(),
   itemId: z.string().optional(),
   unit: z.string(),
-  eventType: z.string().optional(),
+  eventType: z.string(),
   valueProperty: z.string().optional(),
   groupBy: z.record(z.string()).optional(),
   eventFrom: z.date().transform(v => v.toISOString()).optional(),

package/src/models/operations/createtestclock.ts

@@ -6,7 +6,7 @@ import * as z from "zod/v3";
 
 export type CreateTestClockRequest = {
   /**
-   * Initial time for the test clock (defaults to current time). Cannot be more than 1 hour in the past to prevent accidental backdating. The 1-hour buffer accounts for clock drift and network delays.
+   * Initial time for the test clock (defaults to current time). May be in the past, which lets a subscription on the clock start on a past date and bill its periods as the clock advances.
    */
   currentTime?: Date | undefined;
   /**

package/src/models/operations/updatebillablemetric.ts

@@ -23,11 +23,11 @@ export type UpdateBillableMetricRequestBody = {
    */
   itemId?: string | null | undefined;
   /**
-   * CloudEvents type for meter routing.
+   * CloudEvents type for meter routing. Cannot be cleared: every billable metric needs one.
    */
-  eventType?: string | null | undefined;
+  eventType?: string | undefined;
   /**
-   * JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`).
+   * JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`). Cannot be cleared on a SUM/AVG/MIN/MAX/LATEST metric. Not stored for COUNT.
    */
   valueProperty?: string | null | undefined;
   /**
@@ -51,7 +51,7 @@ export type UpdateBillableMetricRequestBody$Outbound = {
   name?: string | undefined;
   unit?: string | undefined;
   itemId?: string | null | undefined;
-  eventType?: string | null | undefined;
+  eventType?: string | undefined;
   valueProperty?: string | null | undefined;
   groupBy?: { [k: string]: string } | null | undefined;
   eventFrom?: string | null | undefined;
@@ -67,7 +67,7 @@ export const UpdateBillableMetricRequestBody$outboundSchema: z.ZodType<
   name: z.string().optional(),
   unit: z.string().optional(),
   itemId: z.nullable(z.string()).optional(),
-  eventType: z.nullable(z.string()).optional(),
+  eventType: z.string().optional(),
   valueProperty: z.nullable(z.string()).optional(),
   groupBy: z.nullable(z.record(z.string())).optional(),
   eventFrom: z.nullable(z.date().transform(v => v.toISOString())).optional(),

package/src/models/profitabilityrow.ts

@@ -21,7 +21,7 @@ export type ProfitabilityRow = {
    */
   customerName: string;
   /**
-   * Net revenue (paid + outstanding) in unit currency, with two decimals.
+   * Revenue excluding tax (paid + outstanding invoices issued in the period), in unit currency, with two decimals.
    */
   netRevenue: string;
   /**

package/src/models/profitabilitysummaryresponse.ts

@@ -25,6 +25,20 @@ export type ProfitabilitySummaryResponseRevenueRange = {
   to: Date;
 };
 
+/**
+ * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.
+ */
+export type ProfitabilitySummaryResponseCostRange = {
+  /**
+   * Earliest cost event instant.
+   */
+  from: Date;
+  /**
+   * Latest cost event instant.
+   */
+  to: Date;
+};
+
 export type ProfitabilitySummaryResponse = {
   /**
    * Object type identifier
@@ -46,6 +60,10 @@ export type ProfitabilitySummaryResponse = {
    * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
    */
   revenueRange?: ProfitabilitySummaryResponseRevenueRange | null | undefined;
+  /**
+   * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.
+   */
+  costRange?: ProfitabilitySummaryResponseCostRange | null | undefined;
 };
 
 /** @internal */
@@ -74,6 +92,27 @@ export function profitabilitySummaryResponseRevenueRangeFromJSON(
   );
 }
 
+/** @internal */
+export const ProfitabilitySummaryResponseCostRange$inboundSchema: z.ZodType<
+  ProfitabilitySummaryResponseCostRange,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  from: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  to: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+});
+
+export function profitabilitySummaryResponseCostRangeFromJSON(
+  jsonString: string,
+): SafeParseResult<ProfitabilitySummaryResponseCostRange, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      ProfitabilitySummaryResponseCostRange$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ProfitabilitySummaryResponseCostRange' from JSON`,
+  );
+}
+
 /** @internal */
 export const ProfitabilitySummaryResponse$inboundSchema: z.ZodType<
   ProfitabilitySummaryResponse,
@@ -87,6 +126,9 @@ export const ProfitabilitySummaryResponse$inboundSchema: z.ZodType<
   revenueRange: z.nullable(
     z.lazy(() => ProfitabilitySummaryResponseRevenueRange$inboundSchema),
   ).optional(),
+  costRange: z.nullable(
+    z.lazy(() => ProfitabilitySummaryResponseCostRange$inboundSchema),
+  ).optional(),
 });
 
 export function profitabilitySummaryResponseFromJSON(

package/src/models/revenuesummaryresponse.ts

@@ -47,11 +47,11 @@ export type RevenueSummaryResponse = {
    */
   object: "revenue_summary";
   /**
-   * Net collected revenue in dollars (paid invoices + completed payments), already net of non-voided refunds. Omitted when groupBy=currency is active.
+   * Revenue in dollars, excluding tax: invoices issued in the period plus completed payments, less non-voided refunds issued in the period. Invoices and refunds are counted excluding tax. Omitted when groupBy=currency is active.
    */
   netRevenue?: string | undefined;
   /**
-   * Gross total of non-voided refunds (credit notes) issued in the period, in dollars. Already subtracted from netRevenue and invoice totals. Omitted when groupBy=currency is active.
+   * Total of non-voided refunds (credit notes) issued in the period, in dollars, including tax. netRevenue subtracts these refunds excluding tax. Omitted when groupBy=currency is active.
    */
   totalRefunds?: string | undefined;
   /**

package/src/models/revenuetrendbucket.ts

@@ -17,7 +17,7 @@ export type RevenueTrendBucket = {
    */
   timestamp: Date;
   /**
-   * Total amount of all invoices issued in this bucket (all statuses, by issuedAt)
+   * Total amount of all invoices issued in this bucket (all statuses, by issuedAt), excluding tax
    */
   issuedInvoices: string;
   /**

package/src/models/subscriptionadjustment.ts

@@ -18,6 +18,8 @@ export type SubscriptionAdjustmentObject = ClosedEnum<
 export const SubscriptionAdjustmentType = {
   PercentageDiscount: "percentageDiscount",
   UsageDiscount: "usageDiscount",
+  MinimumQuantity: "minimumQuantity",
+  MaximumQuantity: "maximumQuantity",
 } as const;
 export type SubscriptionAdjustmentType = ClosedEnum<
   typeof SubscriptionAdjustmentType
@@ -35,27 +37,35 @@ export type SubscriptionAdjustment = {
   subscriptionId: string;
   type: SubscriptionAdjustmentType;
   /**
-   * The discount rate as a decimal fraction between 0 and 1. "0.35" means 35 percent. Null on a usageDiscount, which carries a unit count instead.
+   * The discount rate as a decimal fraction between 0 and 1. "0.35" means 35 percent. Null on every other type.
    */
   percentageDiscount: string | null;
   /**
-   * The number of usage units taken off the targeted line's billable quantity. Null on a percentageDiscount, which carries a rate instead.
+   * The number of usage units taken off the targeted line's billable quantity. Null on every other type.
    */
   usageDiscount: string | null;
   /**
-   * The prices this adjustment reduces. Exactly one metered price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge.
+   * The contracted minimum quantity billed for one period of the targeted price. Null on every other type.
+   */
+  minimumQuantity: string | null;
+  /**
+   * The contracted maximum quantity billed for one period of the targeted price. Null on every other type.
+   */
+  maximumQuantity: string | null;
+  /**
+   * The prices this adjustment applies to. Exactly one price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge. A minimumQuantity or maximumQuantity is created against exactly one price, and later lists more than one only where that charge moved to a new price — a floating subscription moving to a new plan version, or a price edit freezing the subscription's version. Every id listed is the same charge, and the bound applies to whichever one a period bills under.
    */
   targetPriceIds: Array<string>;
   /**
-   * Opens the window. Read per type: INCLUSIVE on a percentageDiscount, whose window is prorated by day overlap; EXCLUSIVE on a usageDiscount, which corrects a line whose period END falls strictly after this instant.
+   * Opens the window. Read per type: INCLUSIVE on a percentageDiscount, whose window is prorated by day overlap; EXCLUSIVE on a usageDiscount and on both quantity bounds, which apply to a line whose period END falls strictly after this instant.
    */
   effectiveFrom: Date;
   /**
-   * Closes the window, or null for never. Read per type: EXCLUSIVE on a percentageDiscount; INCLUSIVE on a usageDiscount, which corrects a line whose period END falls on or before this instant.
+   * Closes the window, or null for never. Read per type: EXCLUSIVE on a percentageDiscount; INCLUSIVE on a usageDiscount and on both quantity bounds, which apply to a line whose period END falls on or before this instant. A delete shortens this to the end of the last period the adjustment has already been billed on.
    */
   effectiveTo: Date | null;
   /**
-   * The deal's own name. Shown on each discount line a percentageDiscount emits; a usageDiscount emits no line, so its description is carried here only.
+   * The deal's own name. Shown on each discount line a percentageDiscount emits; every other type emits no line, so its description is carried here only.
    */
   description: string | null;
   createdAt: Date;
@@ -83,6 +93,8 @@ export const SubscriptionAdjustment$inboundSchema: z.ZodType<
   type: SubscriptionAdjustmentType$inboundSchema,
   percentageDiscount: z.nullable(z.string()),
   usageDiscount: z.nullable(z.string()),
+  minimumQuantity: z.nullable(z.string()),
+  maximumQuantity: z.nullable(z.string()),
   targetPriceIds: z.array(z.string()),
   effectiveFrom: z.string().datetime({ offset: true }).transform(v =>
     new Date(v)

package/src/sdk/subscriptions.ts

@@ -166,12 +166,12 @@ export class Subscriptions extends ClientSDK {
    * Delete Adjustment
    *
    * @remarks
-   * Deletes an adjustment that has not yet reached an issued invoice. No invoice changes: an invoice still in draft keeps its numbers, and loses the discount only when its period is calculated again. An adjustment that has already discounted an issued invoice cannot be deleted, because the invoice records why the customer was charged that amount. Its window cannot be shortened afterwards either, so set effectiveTo at creation time whenever the deal has a known end date.
+   * Stops an adjustment from applying to any period it has not already been billed on. An adjustment that has never reached an issued invoice is removed, and the response is 204. An adjustment that has already been billed on an issued invoice is RETRACTED instead: its effectiveTo moves to the end of the last period it was billed on, the adjustment still exists, and the response is 200 carrying it. Read a 200 as "shortened", not as "removed". No invoice changes either way: an issued invoice keeps its numbers, and a draft loses the adjustment only when its period is calculated again. Deleting the same adjustment again returns the same 200 and the same window.
    */
   async deleteSubscriptionAdjustment(
     request: operations.DeleteSubscriptionAdjustmentRequest,
     options?: RequestOptions,
-  ): Promise<void> {
+  ): Promise<models.SubscriptionAdjustment | undefined> {
     return unwrapAsync(subscriptionsDeleteSubscriptionAdjustment(
       this,
       request,