@paygentic/sdk 0.8.6 → 0.9.0

package/src/models/billablemetric.ts

@@ -44,6 +44,10 @@ export type BillableMetric = {
    * Unique identifier for a product
    */
   productId: string;
+  /**
+   * The item this metric is tagged with, or null when untagged. Used to map this metric's invoice lines to an external accounting/tax identity.
+   */
+  itemId: string | null;
   unit: string;
   updatedAt: Date;
   eventType?: string | null | undefined;
@@ -76,6 +80,7 @@ export const BillableMetric$inboundSchema: z.ZodType<
   merchantId: z.string(),
   name: z.string(),
   productId: z.string(),
+  itemId: z.nullable(z.string()),
   unit: z.string(),
   updatedAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
   eventType: z.nullable(z.string()).optional(),

package/src/models/costusageresponse.ts

@@ -46,6 +46,10 @@ export type CostUsageResponse = {
    * CloudEvents type for metered costs.
    */
   eventType?: string | undefined;
+  /**
+   * Unit label for metered costs (e.g. 'token', 'request'). Absent when the cost defines no unit.
+   */
+  unit?: string | undefined;
   /**
    * Total cost for the query window. Null if usage data could not be computed.
    */
@@ -128,6 +132,7 @@ export const CostUsageResponse$inboundSchema: z.ZodType<
   type: CostUsageResponseType$inboundSchema,
   currency: z.string(),
   eventType: z.string().optional(),
+  unit: z.string().optional(),
   totalCost: z.nullable(z.number()),
   totalQuantity: z.nullable(z.number()).optional(),
   groups: z.array(z.lazy(() => Group$inboundSchema)).optional(),

package/src/models/createbillingschedulerequest.ts

@@ -36,6 +36,9 @@ export type CreateBillingScheduleRequestPeriodPreset = ClosedEnum<
 
 export type CreateBillingScheduleRequest = {
   orderId?: string | undefined;
+  /**
+   * Not supported for creating a billing schedule. Use orderId — every billing schedule belongs to an order.
+   */
   subscriptionId?: string | undefined;
   startDate: Date;
   endDate: Date;

package/src/models/createmanuallineitemrequest.ts

@@ -49,6 +49,10 @@ export type CreateManualLineItemRequest = {
    * Optional caller-provided idempotency key. Auto-generated if not provided.
    */
   idempotencyKey?: string | null | undefined;
+  /**
+   * Optional item to tag this line with, for accounting/GL mapping. Must belong to the caller's merchant and must not be archived. A manual line has no price, so it is never reached by a later restamp — supplying it here is the only opportunity to tag it.
+   */
+  itemId?: string | null | undefined;
 };
 
 /** @internal */
@@ -64,6 +68,7 @@ export type CreateManualLineItemRequest$Outbound = {
   periodStart?: string | null | undefined;
   periodEnd?: string | null | undefined;
   idempotencyKey?: string | null | undefined;
+  itemId?: string | null | undefined;
 };
 
 /** @internal */
@@ -83,6 +88,7 @@ export const CreateManualLineItemRequest$outboundSchema: z.ZodType<
   periodStart: z.nullable(z.date().transform(v => v.toISOString())).optional(),
   periodEnd: z.nullable(z.date().transform(v => v.toISOString())).optional(),
   idempotencyKey: z.nullable(z.string()).optional(),
+  itemId: z.nullable(z.string()).optional(),
 });
 
 export function createManualLineItemRequestToJSON(

package/src/models/errors/deleteprice.ts

@@ -0,0 +1,61 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import * as operations from "../operations/index.js";
+import { PaygenticError } from "./paygenticerror.js";
+
+/**
+ * Price cannot be deleted because a live plan still references it
+ */
+export type DeletePriceConflictErrorData = {
+  error?: string | undefined;
+  message?: string | undefined;
+  details?: operations.DeletePriceDetails | undefined;
+};
+
+/**
+ * Price cannot be deleted because a live plan still references it
+ */
+export class DeletePriceConflictError extends PaygenticError {
+  error?: string | undefined;
+  details?: operations.DeletePriceDetails | undefined;
+
+  /** The original data that was passed to this error instance. */
+  data$: DeletePriceConflictErrorData;
+
+  constructor(
+    err: DeletePriceConflictErrorData,
+    httpMeta: { response: Response; request: Request; body: string },
+  ) {
+    const message = err.message || `API error occurred: ${JSON.stringify(err)}`;
+    super(message, httpMeta);
+    this.data$ = err;
+    if (err.error != null) this.error = err.error;
+    if (err.details != null) this.details = err.details;
+
+    this.name = "DeletePriceConflictError";
+  }
+}
+
+/** @internal */
+export const DeletePriceConflictError$inboundSchema: z.ZodType<
+  DeletePriceConflictError,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  error: z.string().optional(),
+  message: z.string().optional(),
+  details: z.lazy(() => operations.DeletePriceDetails$inboundSchema).optional(),
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
+})
+  .transform((v) => {
+    return new DeletePriceConflictError(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
+  });

package/src/models/errors/index.ts

@@ -5,6 +5,7 @@
 export * from "./badrequest.js";
 export * from "./deletecustomer.js";
 export * from "./deletefee.js";
+export * from "./deleteprice.js";
 export * from "./error.js";
 export * from "./httpclienterrors.js";
 export * from "./paygenticdefaulterror.js";

package/src/models/fee.ts

@@ -26,6 +26,10 @@ export type Fee = {
    * Unique identifier for a product
    */
   productId: string;
+  /**
+   * The item this fee is tagged with, or null when untagged. Used to map this fee's invoice lines to an external accounting/tax identity.
+   */
+  itemId: string | null;
   createdAt: Date;
   updatedAt: Date;
 };
@@ -43,6 +47,7 @@ export const Fee$inboundSchema: z.ZodType<Fee, z.ZodTypeDef, unknown> = z
     description: z.string(),
     merchantId: z.string(),
     productId: z.string(),
+    itemId: z.nullable(z.string()),
     createdAt: z.string().datetime({ offset: true }).transform(v =>
       new Date(v)
     ),

package/src/models/index.ts

@@ -48,6 +48,7 @@ export * from "./item.js";
 export * from "./lineitem.js";
 export * from "./lineitemsresponse.js";
 export * from "./lineitemssummary.js";
+export * from "./mappingcapabilities.js";
 export * from "./merchantintegration.js";
 export * from "./merchantintegrationprovider.js";
 export * from "./merchantintegrationstatus.js";
@@ -86,6 +87,7 @@ export * from "./reconciledfeaturefailed.js";
 export * from "./reconciledfeatureremoved.js";
 export * from "./reconciledfeatureskipped.js";
 export * from "./replacescheduleintervalsrequest.js";
+export * from "./resolveditem.js";
 export * from "./revenuesummaryresponse.js";
 export * from "./revenuetrendbucket.js";
 export * from "./rulecondition.js";

package/src/models/invoice.ts

@@ -11,6 +11,7 @@ import {
   InvoiceLineItem,
   InvoiceLineItem$inboundSchema,
 } from "./invoicelineitem.js";
+import { ResolvedItem, ResolvedItem$inboundSchema } from "./resolveditem.js";
 
 /**
  * The object type
@@ -24,7 +25,7 @@ export const InvoiceObject = {
 export type InvoiceObject = ClosedEnum<typeof InvoiceObject>;
 
 /**
- * Line items (only present if expand=lineItems query parameter is provided)
+ * Line items (only present if expand=lineItems query parameter is provided, or if expand=items is, which implies it)
  */
 export type InvoiceLineItems = {
   /**
@@ -35,6 +36,10 @@ export type InvoiceLineItems = {
    * Array of line items for this page
    */
   lineItems: Array<InvoiceLineItem>;
+  /**
+   * Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not the whole invoice — combine the collections across pages for an invoice-wide set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it.
+   */
+  items?: Array<ResolvedItem> | undefined;
   /**
    * Token for fetching the next page, null if no more pages
    */
@@ -45,6 +50,18 @@ export type InvoiceLineItems = {
   totalCount: number;
 };
 
+/**
+ * Who produced the document at pdfUrl, or null when there is none. `paygentic` means pdfUrl is this API's download endpoint and the request must carry your API key; `tax_provider` means it is the provider's own link, which opens directly in a browser.
+ */
+export const PdfSource = {
+  Paygentic: "paygentic",
+  TaxProvider: "tax_provider",
+} as const;
+/**
+ * Who produced the document at pdfUrl, or null when there is none. `paygentic` means pdfUrl is this API's download endpoint and the request must carry your API key; `tax_provider` means it is the provider's own link, which opens directly in a browser.
+ */
+export type PdfSource = ClosedEnum<typeof PdfSource>;
+
 /**
  * The current status of the invoice
  */
@@ -154,7 +171,7 @@ export type Invoice = {
    */
   itemCount: number;
   /**
-   * Line items (only present if expand=lineItems query parameter is provided)
+   * Line items (only present if expand=lineItems query parameter is provided, or if expand=items is, which implies it)
    */
   lineItems?: InvoiceLineItems | null | undefined;
   /**
@@ -186,9 +203,13 @@ export type Invoice = {
    */
   paymentUrl?: string | null | undefined;
   /**
-   * Direct PDF download link for tax invoice
+   * Link to the invoice document, or null when there is none. For Paygentic-rendered documents this is GET /v2/invoices/{id}/pdf, which requires authentication; for documents supplied by the tax provider it is the provider's own direct link. The URL is stable and does not expire. Branch on pdfSource rather than on the shape of this URL.
    */
   pdfUrl?: string | null | undefined;
+  /**
+   * Who produced the document at pdfUrl, or null when there is none. `paygentic` means pdfUrl is this API's download endpoint and the request must carry your API key; `tax_provider` means it is the provider's own link, which opens directly in a browser.
+   */
+  pdfSource?: PdfSource | null | undefined;
   /**
    * The end of the billing period
    */
@@ -252,6 +273,7 @@ export const InvoiceLineItems$inboundSchema: z.ZodType<
 > = z.object({
   invoiceId: z.string(),
   lineItems: z.array(InvoiceLineItem$inboundSchema),
+  items: z.array(ResolvedItem$inboundSchema).optional(),
   nextPageToken: z.nullable(z.string()).optional(),
   totalCount: z.number().int(),
 });
@@ -266,6 +288,10 @@ export function invoiceLineItemsFromJSON(
   );
 }
 
+/** @internal */
+export const PdfSource$inboundSchema: z.ZodNativeEnum<typeof PdfSource> = z
+  .nativeEnum(PdfSource);
+
 /** @internal */
 export const InvoiceStatus$inboundSchema: z.ZodNativeEnum<
   typeof InvoiceStatus
@@ -333,6 +359,7 @@ export const Invoice$inboundSchema: z.ZodType<Invoice, z.ZodTypeDef, unknown> =
     ).optional(),
     paymentUrl: z.nullable(z.string()).optional(),
     pdfUrl: z.nullable(z.string()).optional(),
+    pdfSource: z.nullable(PdfSource$inboundSchema).optional(),
     periodEnd: z.string().datetime({ offset: true }).transform(v =>
       new Date(v)
     ),

package/src/models/invoicelineitem.ts

@@ -52,6 +52,14 @@ export type InvoiceLineItem = {
    * HOTFIX: Mirrors eventSourceId for backward compatibility
    */
   billableMetricId: string;
+  /**
+   * Item the line's charge was tagged with, recorded when the line was generated and not re-resolved on read. A discount line carries the same item as the charge it offsets. `null` means the charge carried no tag at that moment, the line predates item stamping, or the line has no originating charge (a grant-credit purchase) — it is an expected value, not an error. Use `priceId` to tell those cases apart.
+   */
+  itemId?: string | null | undefined;
+  /**
+   * The price this line was generated from, or `null` when the line has no originating charge. With `itemId` it says whether a missing tag is fixable: `priceId` set and `itemId` null means the charge was simply untagged, which tagging it and restamping resolves; both null means the line records a grant-credit purchase, which is deferred revenue and is never tagged. Any measure of outstanding mapping work must exclude the latter or it can never reach zero.
+   */
+  priceId?: string | null | undefined;
   /**
    * Display name for this line item on invoices
    */
@@ -121,6 +129,8 @@ export const InvoiceLineItem$inboundSchema: z.ZodType<
   eventId: z.string(),
   eventSourceId: z.string(),
   billableMetricId: z.string(),
+  itemId: z.nullable(z.string()).optional(),
+  priceId: z.nullable(z.string()).optional(),
   invoiceDisplayName: z.string(),
   lineItemType: InvoiceLineItemLineItemType$inboundSchema,
   meterEventId: z.string(),

package/src/models/invoicelineitemsresponse.ts

@@ -10,6 +10,7 @@ import {
   InvoiceLineItem,
   InvoiceLineItem$inboundSchema,
 } from "./invoicelineitem.js";
+import { ResolvedItem, ResolvedItem$inboundSchema } from "./resolveditem.js";
 
 export type InvoiceLineItemsResponse = {
   /**
@@ -20,6 +21,10 @@ export type InvoiceLineItemsResponse = {
    * Array of line items for this page
    */
   lineItems: Array<InvoiceLineItem>;
+  /**
+   * Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not the whole invoice — combine the collections across pages for an invoice-wide set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it.
+   */
+  items?: Array<ResolvedItem> | undefined;
   /**
    * Token for fetching the next page, null if no more pages
    */
@@ -38,6 +43,7 @@ export const InvoiceLineItemsResponse$inboundSchema: z.ZodType<
 > = z.object({
   invoiceId: z.string(),
   lineItems: z.array(InvoiceLineItem$inboundSchema),
+  items: z.array(ResolvedItem$inboundSchema).optional(),
   nextPageToken: z.nullable(z.string()).optional(),
   totalCount: z.number().int(),
 });

package/src/models/item.ts

@@ -18,12 +18,23 @@ export const ItemObject = {
 export type ItemObject = ClosedEnum<typeof ItemObject>;
 
 export type Item = {
+  /**
+   * Unique identifier for an item
+   */
   id: string;
   object: ItemObject;
   merchantId: string;
   name: string;
   metadata: { [k: string]: any };
   externalReferences: Array<ExternalReference>;
+  /**
+   * The product this item belongs to.
+   */
+  catalogId: string | null;
+  /**
+   * When this item was retired from the catalog. Null while active.
+   */
+  archivedAt: Date | null;
   createdAt: Date;
   updatedAt: Date;
 };
@@ -41,6 +52,10 @@ export const Item$inboundSchema: z.ZodType<Item, z.ZodTypeDef, unknown> = z
     name: z.string(),
     metadata: z.record(z.any()),
     externalReferences: z.array(ExternalReference$inboundSchema),
+    catalogId: z.nullable(z.string()),
+    archivedAt: z.nullable(
+      z.string().datetime({ offset: true }).transform(v => new Date(v)),
+    ),
     createdAt: z.string().datetime({ offset: true }).transform(v =>
       new Date(v)
     ),

package/src/models/lineitem.ts

@@ -35,14 +35,14 @@ export const LineItemStatus = {
 export type LineItemStatus = ClosedEnum<typeof LineItemStatus>;
 
 /**
- * Payment term for fee items. Null for metered/manual lines
+ * Payment term for fee items. Null for metered/manual lines. `null` is listed in the enum as well as via `nullable` because OpenAPI 3.0 validators check the enum independently — `nullable: true` alone does not admit it, and createLineItem (which always returns null here) was emitting a schema-violating body.
  */
 export const LineItemPaymentTerm = {
   InAdvance: "in_advance",
   InArrears: "in_arrears",
 } as const;
 /**
- * Payment term for fee items. Null for metered/manual lines
+ * Payment term for fee items. Null for metered/manual lines. `null` is listed in the enum as well as via `nullable` because OpenAPI 3.0 validators check the enum independently — `nullable: true` alone does not admit it, and createLineItem (which always returns null here) was emitting a schema-violating body.
  */
 export type LineItemPaymentTerm = ClosedEnum<typeof LineItemPaymentTerm>;
 
@@ -60,9 +60,13 @@ export type LineItem = {
    */
   customerId: string;
   /**
-   * The price ID associated with this line item
+   * The price this line was generated from, or `null` when the line has no originating charge. With `itemId` it says whether a missing tag is fixable: `priceId` set and `itemId` null means the charge was simply untagged, which tagging it and restamping resolves; both null means the line records a grant-credit purchase, which is deferred revenue and is never tagged. Any measure of outstanding mapping work must exclude the latter or it can never reach zero.
    */
   priceId?: string | null | undefined;
+  /**
+   * Item the line's charge was tagged with, recorded when the line was generated and not re-resolved on read. `null` means the charge carried no tag at that moment, the line predates item stamping, or the line has no originating charge (a grant-credit purchase) — it is an expected value, not an error. Use `priceId` to tell those cases apart.
+   */
+  itemId?: string | null | undefined;
   /**
    * The invoice ID if this item has been invoiced
    */
@@ -116,7 +120,7 @@ export type LineItem = {
    */
   meteredQuantity?: string | null | undefined;
   /**
-   * Payment term for fee items. Null for metered/manual lines
+   * Payment term for fee items. Null for metered/manual lines. `null` is listed in the enum as well as via `nullable` because OpenAPI 3.0 validators check the enum independently — `nullable: true` alone does not admit it, and createLineItem (which always returns null here) was emitting a schema-violating body.
    */
   paymentTerm?: LineItemPaymentTerm | null | undefined;
   /**
@@ -173,6 +177,7 @@ export const LineItem$inboundSchema: z.ZodType<
   subscriptionId: z.string(),
   customerId: z.string(),
   priceId: z.nullable(z.string()).optional(),
+  itemId: z.nullable(z.string()).optional(),
   invoiceId: z.nullable(z.string()).optional(),
   type: LineItemType$inboundSchema,
   status: LineItemStatus$inboundSchema,

package/src/models/lineitemsresponse.ts

@@ -12,6 +12,7 @@ import {
   LineItemsSummary,
   LineItemsSummary$inboundSchema,
 } from "./lineitemssummary.js";
+import { ResolvedItem, ResolvedItem$inboundSchema } from "./resolveditem.js";
 
 /**
  * The object type
@@ -35,6 +36,10 @@ export type LineItemsResponse = {
    * Array of line items
    */
   data: Array<LineItem>;
+  /**
+   * Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not to any invoice as a whole — combine the collections across pages for a complete set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it.
+   */
+  items?: Array<ResolvedItem> | undefined;
   /**
    * Total number of matching line items
    */
@@ -55,6 +60,7 @@ export const LineItemsResponse$inboundSchema: z.ZodType<
 > = z.object({
   object: LineItemsResponseObject$inboundSchema,
   data: z.array(LineItem$inboundSchema),
+  items: z.array(ResolvedItem$inboundSchema).optional(),
   totalCount: z.number().int(),
   summary: LineItemsSummary$inboundSchema,
 });

package/src/models/mappingcapabilities.ts

@@ -0,0 +1,48 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+
+/**
+ * What this provider does with an item's external codes.
+ *
+ * @remarks
+ *
+ * Two independent capabilities, not one direction: the behaviours are not alternatives. An integration can resolve an incoming item code *and* be sent a selected one on a different path, so a single `inbound`/`outbound` value would have to misdescribe it or forbid one of its operations.
+ *
+ * A capability that is not declared is unavailable rather than inferred. Declaring one does not make a provider connectable — that still requires its credentials and connection lifecycle.
+ */
+export type MappingCapabilities = {
+  /**
+   * A code arriving from this provider must name exactly one of the merchant's items. The lookup key is the code, so several codes may point at one item while each code resolves to one — which is why a code recorded for this purpose is claimed, and a second item claiming it is a conflict.
+   */
+  resolvesItemCodes: boolean;
+  /**
+   * A consumer needs one of an item's codes to send to this provider, and takes the item's designated one (`isDefault`). Because the lookup key is the item, several items may share one code — a chart of accounts exists so that many things sold roll into one account.
+   */
+  sendsItemCodes: boolean;
+};
+
+/** @internal */
+export const MappingCapabilities$inboundSchema: z.ZodType<
+  MappingCapabilities,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  resolvesItemCodes: z.boolean(),
+  sendsItemCodes: z.boolean(),
+});
+
+export function mappingCapabilitiesFromJSON(
+  jsonString: string,
+): SafeParseResult<MappingCapabilities, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => MappingCapabilities$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'MappingCapabilities' from JSON`,
+  );
+}

package/src/models/merchantintegration.ts

@@ -7,6 +7,10 @@ import { safeParse } from "../lib/schemas.js";
 import { ClosedEnum } from "../types/enums.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+import {
+  MappingCapabilities,
+  MappingCapabilities$inboundSchema,
+} from "./mappingcapabilities.js";
 import {
   MerchantIntegrationProvider,
   MerchantIntegrationProvider$inboundSchema,
@@ -37,9 +41,19 @@ export type MerchantIntegration = {
    */
   merchantId: string;
   /**
-   * External provider a merchant can connect at the tenant level
+   * External provider a merchant can connect at the tenant level. `netsuite` and `accountsiq` are returned on reads wherever a connection exists, but connecting them is accepted only in local and development environments; elsewhere the connect request is refused with 404.
    */
   provider: MerchantIntegrationProvider;
+  /**
+   * What this provider does with an item's external codes.
+   *
+   * @remarks
+   *
+   * Two independent capabilities, not one direction: the behaviours are not alternatives. An integration can resolve an incoming item code *and* be sent a selected one on a different path, so a single `inbound`/`outbound` value would have to misdescribe it or forbid one of its operations.
+   *
+   * A capability that is not declared is unavailable rather than inferred. Declaring one does not make a provider connectable — that still requires its credentials and connection lifecycle.
+   */
+  capabilities: MappingCapabilities;
   /**
    * Ampersand installation id.
    */
@@ -73,6 +87,7 @@ export const MerchantIntegration$inboundSchema: z.ZodType<
   ),
   merchantId: z.string(),
   provider: MerchantIntegrationProvider$inboundSchema,
+  capabilities: MappingCapabilities$inboundSchema,
   externalId: z.nullable(z.string()),
   status: MerchantIntegrationStatus$inboundSchema,
   config: z.record(z.any()),

package/src/models/merchantintegrationprovider.ts

@@ -6,13 +6,15 @@ import * as z from "zod/v3";
 import { ClosedEnum } from "../types/enums.js";
 
 /**
- * External provider a merchant can connect at the tenant level
+ * External provider a merchant can connect at the tenant level. `netsuite` and `accountsiq` are returned on reads wherever a connection exists, but connecting them is accepted only in local and development environments; elsewhere the connect request is refused with 404.
  */
 export const MerchantIntegrationProvider = {
   Salesforce: "salesforce",
+  Netsuite: "netsuite",
+  Accountsiq: "accountsiq",
 } as const;
 /**
- * External provider a merchant can connect at the tenant level
+ * External provider a merchant can connect at the tenant level. `netsuite` and `accountsiq` are returned on reads wherever a connection exists, but connecting them is accepted only in local and development environments; elsewhere the connect request is refused with 404.
  */
 export type MerchantIntegrationProvider = ClosedEnum<
   typeof MerchantIntegrationProvider

package/src/models/mintplanversionrequest.ts

@@ -16,7 +16,7 @@ export type ReplacePrice = {
 };
 
 /**
- * A reference-by-id price diff applied to the prices of the plan's current version. Every id references an existing price created via POST /prices; inline price definitions are not accepted. An empty body copies the current prices into the new version unchanged. A version must carry at least one price, so a diff that would leave none is rejected.
+ * A reference-by-id price diff applied to the prices of the plan's current version. Every id references an existing price created via POST /prices; inline price definitions are not accepted. A mint must carry at least one price change, so an empty body is rejected. A version must carry at least one price, so a diff that would leave none is rejected.
  */
 export type MintPlanVersionRequest = {
   /**

package/src/models/operations/createbillablemetric.ts

@@ -44,7 +44,11 @@ export type CreateBillableMetricRequest = {
   /**
    * Unique identifier for a product
    */
-  productId: string;
+  productId?: string | undefined;
+  /**
+   * Unique identifier for an item
+   */
+  itemId?: string | undefined;
   /**
    * Measurement unit used when aggregating this metric's values. Common examples: 'tokens', 'GB', 'calls', 'images', 'hours', 'TB', 'queries', 'requests'
    */
@@ -78,7 +82,8 @@ export type CreateBillableMetricRequest$Outbound = {
   description: string;
   merchantId: string;
   name: string;
-  productId: string;
+  productId?: string | undefined;
+  itemId?: string | undefined;
   unit: string;
   eventType?: string | undefined;
   valueProperty?: string | undefined;
@@ -96,7 +101,8 @@ export const CreateBillableMetricRequest$outboundSchema: z.ZodType<
   description: z.string(),
   merchantId: z.string(),
   name: z.string(),
-  productId: z.string(),
+  productId: z.string().optional(),
+  itemId: z.string().optional(),
   unit: z.string(),
   eventType: z.string().optional(),
   valueProperty: z.string().optional(),

package/src/models/operations/createexternalreference.ts

@@ -32,13 +32,25 @@ export type CreateExternalReferenceRequest = {
    */
   metadata?: { [k: string]: any } | undefined;
   /**
-   * Whether this is the canonical reference for `(provider, externalId)`. The primary is unique per merchant; non-primary references are aliases.
+   * Whether this reference claims `(provider, externalId)` — the code resolves back to this one entity. Unique per merchant; unclaimed references are aliases. **Omitting it claims the code.** Send `false` for a code that is only ever sent outward, such as a ledger account several items post to — claiming that refuses the second item to use it. The default is not derived from the provider: what a code is for is a property of the operation recording it, and one provider can both resolve an arriving code and be sent a selected one. Declaring a schema default here would defeat the distinction, because a generated client materialises the default into the request body and the caller can no longer express "I did not say".
    */
   isPrimary?: boolean | undefined;
   /**
-   * Whether this is the default target for the entity + provider. At most one default per `(entityType, entityId, provider)`.
+   * Whether this is the code sent *to* the provider for this entity. At most one per `(entityType, entityId, provider)`. **Omit** to have the entity's first code for the provider designated automatically — see the note on `isPrimary` for why this carries no schema default.
    */
   isDefault?: boolean | undefined;
+  /**
+   * Take this code's claim from whichever entity currently holds it, in the same transaction.
+   *
+   * @remarks
+   *
+   * Without it, claiming a code another entity claims is a `409` identifying the holder — the right answer to an accident, and the common case. With it, the reassignment is the point.
+   *
+   * It exists because the alternative route — remove the old claim, then create the new one — leaves a window in which the code resolves to nothing. An arrival in that window is still recorded, untagged rather than rejected, so nothing is lost; but it is silent while it lasts and leaves work to repair.
+   *
+   * Deliberately opt-in, unlike moving a designation. A designation moves within one entity; a claim moves *between* entities and changes what future arrivals resolve to, which should never be a side effect of recording a code. Ignored when the write is not claiming the code.
+   */
+  moveClaim?: boolean | undefined;
 };
 
 /** @internal */
@@ -50,8 +62,9 @@ export type CreateExternalReferenceRequest$Outbound = {
   externalId: string;
   externalLabel?: string | undefined;
   metadata?: { [k: string]: any } | undefined;
-  isPrimary: boolean;
-  isDefault: boolean;
+  isPrimary?: boolean | undefined;
+  isDefault?: boolean | undefined;
+  moveClaim?: boolean | undefined;
 };
 
 /** @internal */
@@ -67,8 +80,9 @@ export const CreateExternalReferenceRequest$outboundSchema: z.ZodType<
   externalId: z.string(),
   externalLabel: z.string().optional(),
   metadata: z.record(z.any()).optional(),
-  isPrimary: z.boolean().default(true),
-  isDefault: z.boolean().default(false),
+  isPrimary: z.boolean().optional(),
+  isDefault: z.boolean().optional(),
+  moveClaim: z.boolean().optional(),
 });
 
 export function createExternalReferenceRequestToJSON(