{ "openapi": "3.0.3", "info": { "title": "Boost Connect Management API", "version": "0.1.0", "description": "Customer-facing Boost Connect account, project, token, and webhook management API." }, "servers": [ { "url": "https://boostconnectqbd.boostplugins.app" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "account_id_mismatch", "account_id_required", "account_not_found", "api_rate_limit_exceeded", "catalog_result_not_found", "company_not_found", "qbd_connection_header_required", "connection_disconnected", "connection_id_required", "connection_id_mismatch", "connection_not_found", "customer_id_required", "customer_not_found", "developer_permission_required", "internal_error", "invalid_catalog_entity_type", "invalid_catalog_query", "invalid_completion_mode", "invalid_customer_query", "invalid_json", "invalid_pagination", "invalid_query", "invalid_request", "invalid_token", "management_client_not_allowed", "management_permission_required", "missing_bearer_token", "not_found", "operation_not_found", "operation_queue_limit_exceeded", "project_limit_exceeded", "project_not_found", "qbd_connector_config_invalid", "qbd_read_failed", "qbd_read_timeout", "qbd_live_sort_unsupported", "qbd_snapshot_cursor_expired", "qbd_snapshot_not_ready", "qbd_snapshot_query_unsupported", "resource_id_required", "resource_not_found", "session_not_found", "setup_callback_code_not_found", "setup_callback_code_verifier_invalid", "setup_callback_project_not_found", "setup_callback_unavailable", "setup_callback_url_credentials_invalid", "setup_callback_url_fragment_invalid", "setup_callback_url_insecure", "setup_callback_url_not_allowed", "setup_callback_url_protocol_invalid", "setup_session_not_found", "team_member_not_found", "token_expired", "token_not_found", "unauthorized", "unsupported_qbd_resource", "upstream_request_failed", "user_id_mismatch", "webhook_endpoint_capacity_exceeded", "webhook_endpoint_conflict", "webhook_endpoint_not_found", "webhook_endpoint_store_unavailable" ] }, "message": { "type": "string", "minLength": 1 }, "qbdFailureKind": { "type": "string", "nullable": true, "enum": [ "quickbooks_revision_conflict", "quickbooks_company_file_mismatch", "quickbooks_empty_qbxml_response", "quickbooks_feature_unavailable", "quickbooks_invalid_list_id", "quickbooks_online_processing_required", "quickbooks_personal_data_permission_required", "quickbooks_read_timeout", "quickbooks_sdk_unavailable", null ] } }, "required": [ "error", "message", "qbdFailureKind" ] }, "QbdQwcFileIdentityDto": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "appNameSuffix": { "type": "string", "nullable": true }, "generatedAt": { "type": "string", "format": "date-time" } }, "required": [ "fileId", "appNameSuffix", "generatedAt" ] }, "QbdCompanyIdentityDto": { "type": "object", "properties": { "companyName": { "type": "string", "minLength": 1 }, "legalCompanyName": { "type": "string", "nullable": true }, "fingerprint": { "type": "string", "minLength": 1 }, "capturedAt": { "type": "string", "format": "date-time" } }, "required": [ "companyName", "legalCompanyName", "fingerprint", "capturedAt" ] }, "QbdCompanyIdentityMismatchDto": { "type": "object", "properties": { "expected": { "$ref": "#/components/schemas/QbdCompanyIdentityDto" }, "detected": { "$ref": "#/components/schemas/QbdCompanyIdentityDto" }, "detectedAt": { "type": "string", "format": "date-time" }, "message": { "type": "string", "minLength": 1 } }, "required": [ "expected", "detected", "detectedAt", "message" ] }, "QbdConnectionDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "enum": [ "quickbooks_desktop" ] }, "displayName": { "type": "string", "minLength": 1 }, "externalCustomerId": { "type": "string", "nullable": true }, "externalConnectionId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } }, "status": { "type": "string", "enum": [ "waiting_for_web_connector", "connected", "disconnected", "error", "disabled" ] }, "qwcUsername": { "type": "string", "minLength": 1 }, "qwcFileIdentity": { "allOf": [ { "$ref": "#/components/schemas/QbdQwcFileIdentityDto" }, { "nullable": true } ] }, "companyIdentity": { "allOf": [ { "$ref": "#/components/schemas/QbdCompanyIdentityDto" }, { "nullable": true } ] }, "companyIdentityMismatch": { "allOf": [ { "$ref": "#/components/schemas/QbdCompanyIdentityMismatchDto" }, { "nullable": true } ] }, "qwcPassword": { "type": "string", "nullable": true }, "qwcPasswordForLocalTesting": { "type": "string", "nullable": true }, "queueDepth": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastSuccessAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastErrorAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastErrorMessage": { "type": "string", "nullable": true } }, "required": [ "accountId", "projectId", "connectionId", "provider", "displayName", "externalCustomerId", "externalConnectionId", "metadata", "status", "qwcUsername", "queueDepth", "createdAt", "updatedAt", "lastSeenAt", "lastSuccessAt", "lastErrorAt", "lastErrorMessage" ] }, "QbdPublicConnectionDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "enum": [ "quickbooks_desktop" ] }, "displayName": { "type": "string", "minLength": 1 }, "externalCustomerId": { "type": "string", "nullable": true }, "externalConnectionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "waiting_for_web_connector", "connected", "disconnected", "error", "disabled" ] }, "qwcUsername": { "type": "string", "minLength": 1 }, "companyIdentity": { "allOf": [ { "$ref": "#/components/schemas/QbdCompanyIdentityDto" }, { "nullable": true } ] }, "companyIdentityMismatch": { "allOf": [ { "$ref": "#/components/schemas/QbdCompanyIdentityMismatchDto" }, { "nullable": true } ] }, "queueDepth": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastSuccessAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastErrorAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastErrorMessage": { "type": "string", "nullable": true } }, "required": [ "accountId", "projectId", "connectionId", "provider", "displayName", "externalCustomerId", "externalConnectionId", "status", "qwcUsername", "queueDepth", "createdAt", "updatedAt", "lastSeenAt", "lastSuccessAt", "lastErrorAt", "lastErrorMessage" ] }, "CreateQbdConnectionRequestDto": { "type": "object", "properties": { "mirrorPolicy": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "resourceTypes": { "type": "array", "items": { "type": "string", "enum": [ "customer", "vendor", "service_item", "inventory_item", "non_inventory_item", "other_charge_item", "discount_item", "subtotal_item", "inventory_assembly_item", "item_group", "account", "class", "terms", "invoice", "bill", "sales_order", "estimate", "currency", "customer_type", "payment_method", "price_level", "sales_tax_code", "sales_tax_item", "shipping_method", "sales_representative", "unit_of_measure_set" ] }, "minItems": 1, "maxItems": 26 }, "fieldPolicyVersion": { "type": "string", "enum": [ "qbd-document-entry-v1", "qbd-native-current-v2" ] }, "refreshTargetSeconds": { "type": "integer", "minimum": 900, "maximum": 86400 }, "reconciliationTargetSeconds": { "type": "integer", "minimum": 86400, "maximum": 604800 } }, "required": [ "enabled", "resourceTypes", "fieldPolicyVersion", "refreshTargetSeconds", "reconciliationTargetSeconds" ], "additionalProperties": false }, "displayName": { "type": "string", "nullable": true, "minLength": 1 }, "externalCustomerId": { "type": "string", "nullable": true, "minLength": 1 }, "externalConnectionId": { "type": "string", "nullable": true, "minLength": 1 }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "idempotencyKey": { "type": "string", "nullable": true, "minLength": 1 }, "callback": { "allOf": [ { "$ref": "#/components/schemas/QbdSetupCallbackDto" }, { "nullable": true } ] } } }, "QbdSetupCallbackDto": { "type": "object", "properties": { "callbackUrl": { "type": "string", "minLength": 1, "format": "uri" }, "state": { "type": "string", "minLength": 1, "maxLength": 2048 }, "codeChallenge": { "type": "string", "nullable": true }, "codeChallengeMethod": { "type": "string", "nullable": true, "enum": [ "S256", null ] } }, "required": [ "callbackUrl", "state" ] }, "UpdateQbdConnectionRequestDto": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "waiting_for_web_connector", "connected", "disconnected", "error", "disabled" ] } }, "required": [ "displayName", "status" ] }, "QbdConnectionCreatedDto": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" }, "qwcPassword": { "type": "string", "minLength": 1 }, "qwcDownloadUrl": { "type": "string", "minLength": 1 }, "setupUrl": { "type": "string", "minLength": 1 } }, "required": [ "connection", "qwcPassword", "qwcDownloadUrl", "setupUrl" ] }, "QbdConnectionPasswordResetDto": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" }, "qwcPassword": { "type": "string", "minLength": 1 } }, "required": [ "connection", "qwcPassword" ] }, "QbdConnectionQwcFileResetDto": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" }, "qwcDownloadUrl": { "type": "string", "minLength": 1 } }, "required": [ "connection", "qwcDownloadUrl" ] }, "OverrideQbdCompanyIdentityRequestDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "accept_detected" ] }, "detectedFingerprint": { "type": "string", "minLength": 1 } }, "required": [ "mode", "detectedFingerprint" ] }, "QbdCompanyIdentityOverrideDto": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" }, "previousCompanyIdentity": { "allOf": [ { "$ref": "#/components/schemas/QbdCompanyIdentityDto" }, { "nullable": true } ] }, "acceptedCompanyIdentity": { "$ref": "#/components/schemas/QbdCompanyIdentityDto" } }, "required": [ "connection", "previousCompanyIdentity", "acceptedCompanyIdentity" ] }, "QbdConnectionHealthCheckOperationDto": { "type": "object", "properties": { "operationId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "company_identity_guard", "company_query", "account_query", "account_tax_line_query", "bill_check_payment_query", "bill_credit_card_payment_query", "bills_to_pay_query", "build_assembly_query", "customer_query", "currency_query", "customer_type_query", "vendor_query", "item_query", "class_query", "terms_query", "deleted_list_object_query", "deleted_transaction_query", "discount_item_query", "employee_query", "invoice_query", "bill_query", "estimate_query", "inventory_adjustment_query", "inventory_assembly_item_query", "inventory_item_query", "inventory_site_query", "item_group_query", "item_site_query", "non_inventory_item_query", "other_charge_item_query", "other_name_query", "payment_method_query", "payments_to_deposit_query", "payroll_wage_item_query", "preferences_query", "price_level_query", "report_aging_query", "report_budget_summary_query", "report_custom_detail_query", "report_custom_summary_query", "report_general_detail_query", "report_general_summary_query", "report_job_query", "report_payroll_detail_query", "report_payroll_summary_query", "report_time_query", "sales_receipt_query", "sales_representative_query", "sales_tax_code_query", "sales_tax_item_query", "service_item_query", "shipping_method_query", "subtotal_item_query", "purchase_order_query", "sales_order_query", "template_query", "time_tracking_activity_query", "transaction_query", "transfer_query", "unit_of_measure_set_query", "credit_memo_query", "receive_payment_query", "check_query", "deposit_query", "journal_entry_query", "vendor_credit_query", "credit_card_charge_query", "credit_card_credit_query", "credit_card_refund_query", "item_receipt_query", "invoice_add", "bill_add", "qbxml_passthrough" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "operationId", "kind", "status", "errorMessage", "createdAt", "updatedAt", "startedAt", "completedAt" ] }, "QbdConnectionHealthCheckDto": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" }, "state": { "type": "string", "enum": [ "ready", "busy", "waiting_for_web_connector", "stale", "error", "disabled" ] }, "ready": { "type": "boolean" }, "queueDepth": { "type": "integer", "minimum": 0 }, "pendingOperationCount": { "type": "integer", "minimum": 0 }, "activeOperation": { "allOf": [ { "$ref": "#/components/schemas/QbdConnectionHealthCheckOperationDto" }, { "nullable": true } ] }, "lastSeenAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastSeenAgeSeconds": { "type": "number", "nullable": true }, "checkedAt": { "type": "string", "format": "date-time" } }, "required": [ "connection", "state", "ready", "queueDepth", "pendingOperationCount", "activeOperation", "lastSeenAt", "lastSeenAgeSeconds", "checkedAt" ] }, "QbdConnectionUsageDailyDto": { "type": "object", "properties": { "dateKey": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "source": { "type": "string", "enum": [ "public_api", "portal", "qwc", "internal" ] }, "requestCount": { "type": "integer", "minimum": 0 }, "errorCount": { "type": "integer", "minimum": 0 }, "averageLatencyMs": { "type": "number", "nullable": true }, "maxLatencyMs": { "type": "number", "nullable": true }, "averageQueueDepth": { "type": "number", "nullable": true }, "maxQueueDepth": { "type": "number", "nullable": true } }, "required": [ "dateKey", "source", "requestCount", "errorCount", "averageLatencyMs", "maxLatencyMs", "averageQueueDepth", "maxQueueDepth" ] }, "QbdConnectionUsageMinuteDto": { "type": "object", "properties": { "minuteKey": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "public_api", "portal", "qwc", "internal" ] }, "requestCount": { "type": "integer", "minimum": 0 }, "errorCount": { "type": "integer", "minimum": 0 }, "averageLatencyMs": { "type": "number", "nullable": true }, "maxLatencyMs": { "type": "number", "nullable": true }, "averageQueueDepth": { "type": "number", "nullable": true }, "maxQueueDepth": { "type": "number", "nullable": true } }, "required": [ "minuteKey", "source", "requestCount", "errorCount", "averageLatencyMs", "maxLatencyMs", "averageQueueDepth", "maxQueueDepth" ] }, "QbdConnectionUsageEndpointDto": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1 }, "endpoint": { "type": "string", "minLength": 1 }, "requestCount": { "type": "integer", "minimum": 0 }, "errorCount": { "type": "integer", "minimum": 0 }, "averageLatencyMs": { "type": "number", "nullable": true }, "maxLatencyMs": { "type": "number", "nullable": true } }, "required": [ "method", "endpoint", "requestCount", "errorCount", "averageLatencyMs", "maxLatencyMs" ] }, "QbdConnectionUsageStatusDto": { "type": "object", "properties": { "statusGroup": { "type": "string", "enum": [ "1xx", "2xx", "3xx", "4xx", "5xx", "unknown" ] }, "requestCount": { "type": "integer", "minimum": 0 } }, "required": [ "statusGroup", "requestCount" ] }, "QbdConnectionUsageLocationDto": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1 }, "region": { "type": "string", "nullable": true }, "colo": { "type": "string", "nullable": true }, "requestCount": { "type": "integer", "minimum": 0 }, "averageLatencyMs": { "type": "number", "nullable": true } }, "required": [ "country", "region", "colo", "requestCount", "averageLatencyMs" ] }, "QbdConnectionUsageSummaryDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "totalRequestCount": { "type": "integer", "minimum": 0 }, "totalErrorCount": { "type": "integer", "minimum": 0 }, "averageLatencyMs": { "type": "number", "nullable": true }, "maxLatencyMs": { "type": "number", "nullable": true }, "currentQueueDepth": { "type": "number", "nullable": true }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/QbdConnectionUsageDailyDto" } }, "minutes": { "type": "array", "items": { "$ref": "#/components/schemas/QbdConnectionUsageMinuteDto" } }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/QbdConnectionUsageEndpointDto" } }, "statusGroups": { "type": "array", "items": { "$ref": "#/components/schemas/QbdConnectionUsageStatusDto" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/QbdConnectionUsageLocationDto" } } }, "required": [ "accountId", "connectionId", "totalRequestCount", "totalErrorCount", "averageLatencyMs", "maxLatencyMs", "currentQueueDepth", "daily", "minutes", "endpoints", "statusGroups", "locations" ] }, "BoostConnectApiKeyAuthorizationV2Dto": { "type": "object", "properties": { "version": { "type": "string", "enum": [ "v2" ] }, "projectIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "One or more project IDs assigned to this API key." }, "scopePreset": { "type": "string", "enum": [ "admin", "custom" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "account:write", "connections:read", "connections:write", "credentials:read", "credentials:write", "diagnostics:read", "project:read", "projects:read", "projects:write", "qbd:read", "qbd:write", "setup:create", "webhooks:read", "webhooks:write" ] }, "minItems": 1, "description": "The explicit permissions materialized for this API key." } }, "required": [ "version", "projectIds", "scopePreset", "scopes" ] }, "CreateBoostConnectApiKeyAuthorizationV2RequestDto": { "anyOf": [ { "type": "object", "properties": { "projectIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "One or more project IDs assigned to this API key." }, "scopePreset": { "type": "string", "enum": [ "admin" ] }, "scopes": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "account:read", "account:write", "connections:read", "connections:write", "credentials:read", "credentials:write", "diagnostics:read", "project:read", "projects:read", "projects:write", "qbd:read", "qbd:write", "setup:create", "webhooks:read", "webhooks:write" ] }, "maxItems": 0, "description": "Explicit permissions for a custom API key." } }, "required": [ "projectIds", "scopePreset" ] }, { "type": "object", "properties": { "projectIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "One or more project IDs assigned to this API key." }, "scopePreset": { "type": "string", "enum": [ "custom" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "account:write", "connections:read", "connections:write", "credentials:read", "credentials:write", "diagnostics:read", "project:read", "projects:read", "projects:write", "qbd:read", "qbd:write", "setup:create", "webhooks:read", "webhooks:write" ] }, "minItems": 1, "description": "Explicit permissions for a custom API key." } }, "required": [ "projectIds", "scopePreset", "scopes" ] } ], "description": "Project assignments and access scope for an API key." }, "BoostConnectApiTokenDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "tokenId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "authorization": { "$ref": "#/components/schemas/BoostConnectApiKeyAuthorizationV2Dto" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "tokenPrefix": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "revokedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastUsedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "accountId", "tokenId", "name", "authorization", "tags", "status", "tokenPrefix", "createdAt", "createdBy", "expiresAt", "revokedAt", "lastUsedAt" ] }, "BoostConnectDeveloperPrincipalDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "credentialId": { "type": "string", "minLength": 1 }, "credentialKind": { "type": "string", "enum": [ "api_token", "local_development", "oauth_access_token" ] }, "authorization": { "$ref": "#/components/schemas/BoostConnectApiKeyAuthorizationV2Dto" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "accountId", "credentialId", "credentialKind", "authorization", "expiresAt" ] }, "BoostConnectAccountBrandingDto": { "type": "object", "properties": { "displayName": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "supportUrl": { "type": "string", "nullable": true }, "supportEmail": { "type": "string", "nullable": true }, "accentColor": { "type": "string", "nullable": true }, "qwcAppName": { "type": "string", "nullable": true }, "qwcAppDescription": { "type": "string", "nullable": true } }, "required": [ "displayName", "logoUrl", "supportUrl", "supportEmail", "accentColor", "qwcAppName", "qwcAppDescription" ] }, "BoostConnectProjectCallbacksDto": { "type": "object", "properties": { "allowedUrls": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "allowedUrls" ] }, "BoostConnectProjectDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "isDefault": { "type": "boolean" }, "branding": { "$ref": "#/components/schemas/BoostConnectAccountBrandingDto" }, "callbacks": { "$ref": "#/components/schemas/BoostConnectProjectCallbacksDto" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "projectId", "name", "tags", "status", "isDefault", "branding", "callbacks", "createdAt", "updatedAt" ] }, "UpdateBoostConnectAccountBrandingRequestDto": { "type": "object", "properties": { "displayName": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "supportUrl": { "type": "string", "nullable": true }, "supportEmail": { "type": "string", "nullable": true }, "accentColor": { "type": "string", "nullable": true }, "qwcAppName": { "type": "string", "nullable": true }, "qwcAppDescription": { "type": "string", "nullable": true } } }, "UpdateBoostConnectProjectCallbacksRequestDto": { "type": "object", "properties": { "allowedUrls": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } } } }, "CreateBoostConnectProjectRequestDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "minLength": 1 }, "tags": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } } } }, "UpdateBoostConnectProjectRequestDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "minLength": 1 }, "tags": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "nullable": true, "enum": [ "active", "archived", null ] }, "branding": { "allOf": [ { "$ref": "#/components/schemas/UpdateBoostConnectAccountBrandingRequestDto" }, { "nullable": true } ] }, "callbacks": { "allOf": [ { "$ref": "#/components/schemas/UpdateBoostConnectProjectCallbacksRequestDto" }, { "nullable": true } ] } } }, "BoostConnectApiTokenCreatedDto": { "type": "object", "properties": { "token": { "$ref": "#/components/schemas/BoostConnectApiTokenDto" }, "bearerToken": { "type": "string", "minLength": 1 } }, "required": [ "token", "bearerToken" ] }, "CreateBoostConnectApiTokenRequestDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "minLength": 1 }, "authorization": { "$ref": "#/components/schemas/CreateBoostConnectApiKeyAuthorizationV2RequestDto" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "tags": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } } }, "required": [ "authorization" ] }, "UpdateBoostConnectApiTokenRequestDto": { "type": "object", "properties": { "authorization": { "$ref": "#/components/schemas/CreateBoostConnectApiKeyAuthorizationV2RequestDto" }, "tags": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } } } }, "QbdOperationDto": { "type": "object", "properties": { "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "unavailable", "expired", "uncertain" ] }, "companyFingerprint": { "type": "string", "nullable": true }, "generationId": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "records": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "id": { "type": "string" }, "revisionNumber": { "type": "string", "nullable": true }, "refNumber": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "parentLineId": { "type": "string", "nullable": true }, "itemId": { "type": "string", "nullable": true } }, "required": [ "id", "parentLineId", "itemId" ] } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "revisionNumber": { "type": "string", "nullable": true }, "parentCustomerId": { "type": "string" } }, "required": [ "id", "revisionNumber", "parentCustomerId" ] }, "description": "All contact identities returned in the confirmed customer response; not just the new contact. Compare IDs with the pre-write customer. No personal contact fields are retained in this receipt." } }, "required": [ "resourceType", "id", "revisionNumber", "refNumber", "lines" ] } } }, "required": [ "status", "companyFingerprint", "generationId", "expiresAt", "records" ] }, "accountId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "operationId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "company_identity_guard", "company_query", "account_query", "account_tax_line_query", "bill_check_payment_query", "bill_credit_card_payment_query", "bills_to_pay_query", "build_assembly_query", "customer_query", "currency_query", "customer_type_query", "vendor_query", "item_query", "class_query", "terms_query", "deleted_list_object_query", "deleted_transaction_query", "discount_item_query", "employee_query", "invoice_query", "bill_query", "estimate_query", "inventory_adjustment_query", "inventory_assembly_item_query", "inventory_item_query", "inventory_site_query", "item_group_query", "item_site_query", "non_inventory_item_query", "other_charge_item_query", "other_name_query", "payment_method_query", "payments_to_deposit_query", "payroll_wage_item_query", "preferences_query", "price_level_query", "report_aging_query", "report_budget_summary_query", "report_custom_detail_query", "report_custom_summary_query", "report_general_detail_query", "report_general_summary_query", "report_job_query", "report_payroll_detail_query", "report_payroll_summary_query", "report_time_query", "sales_receipt_query", "sales_representative_query", "sales_tax_code_query", "sales_tax_item_query", "service_item_query", "shipping_method_query", "subtotal_item_query", "purchase_order_query", "sales_order_query", "template_query", "time_tracking_activity_query", "transaction_query", "transfer_query", "unit_of_measure_set_query", "credit_memo_query", "receive_payment_query", "check_query", "deposit_query", "journal_entry_query", "vendor_credit_query", "credit_card_charge_query", "credit_card_credit_query", "credit_card_refund_query", "item_receipt_query", "invoice_add", "bill_add", "qbxml_passthrough" ] }, "qbdResourceName": { "type": "string", "nullable": true, "enum": [ "account-tax-lines", "accounts", "bill-check-payments", "bill-credit-card-payments", "bills", "bills-to-pay", "build-assemblies", "checks", "classes", "company", "credit-card-charges", "credit-card-credits", "credit-card-refunds", "credit-memos", "currencies", "customer-types", "customers", "date-driven-terms", "deleted-list-objects", "deleted-transactions", "deposits", "discount-items", "employees", "estimates", "inventory-adjustments", "inventory-assembly-items", "inventory-items", "inventory-sites", "invoices", "item-groups", "item-receipts", "item-sites", "journal-entries", "non-inventory-items", "other-charge-items", "other-names", "payment-methods", "payments-to-deposit", "payroll-wage-items", "preferences", "price-levels", "purchase-orders", "receive-payments", "sales-orders", "sales-representatives", "sales-receipts", "sales-tax-codes", "sales-tax-items", "service-items", "shipping-methods", "standard-terms", "subtotal-items", "templates", "time-tracking-activities", "transactions", "transfers", "unit-of-measure-sets", "vendor-credits", "vendors", null ] }, "qbdWriteAction": { "type": "string", "nullable": true, "enum": [ "create", "update", "delete", "void", null ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "priority": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 100 ] }, { "type": "number", "enum": [ 200 ] }, { "type": "number", "enum": [ 300 ] } ] }, "idempotencyKey": { "type": "string", "nullable": true }, "requestXmlObjectKey": { "type": "string", "nullable": true }, "responseXmlObjectKey": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "attemptCount": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "leaseExpiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "claimedByTicket": { "type": "string", "nullable": true }, "lastQbStatusCode": { "type": "number", "nullable": true }, "lastQbStatusSeverity": { "type": "string", "nullable": true, "enum": [ "info", "warning", "error", "unknown", null ] }, "lastQbStatusMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "availableAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" }, "suppressWebhooks": { "type": "boolean" } }, "required": [ "accountId", "connectionId", "operationId", "kind", "status", "priority", "idempotencyKey", "requestXmlObjectKey", "responseXmlObjectKey", "errorMessage", "attemptCount", "maxAttempts", "leaseExpiresAt", "claimedByTicket", "lastQbStatusCode", "lastQbStatusSeverity", "lastQbStatusMessage", "createdAt", "updatedAt", "availableAt", "startedAt", "completedAt" ] }, "QbdWriteResultDto": { "type": "object", "properties": { "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "unavailable", "expired", "uncertain" ] }, "companyFingerprint": { "type": "string", "nullable": true }, "generationId": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "records": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "id": { "type": "string" }, "revisionNumber": { "type": "string", "nullable": true }, "refNumber": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "parentLineId": { "type": "string", "nullable": true }, "itemId": { "type": "string", "nullable": true } }, "required": [ "id", "parentLineId", "itemId" ] } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "revisionNumber": { "type": "string", "nullable": true }, "parentCustomerId": { "type": "string" } }, "required": [ "id", "revisionNumber", "parentCustomerId" ] }, "description": "All contact identities returned in the confirmed customer response; not just the new contact. Compare IDs with the pre-write customer. No personal contact fields are retained in this receipt." } }, "required": [ "resourceType", "id", "revisionNumber", "refNumber", "lines" ] } } }, "required": [ "status", "companyFingerprint", "generationId", "expiresAt", "records" ] }, "status": { "type": "string", "enum": [ "processing", "posted", "failed" ] }, "operationId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "company_identity_guard", "company_query", "account_query", "account_tax_line_query", "bill_check_payment_query", "bill_credit_card_payment_query", "bills_to_pay_query", "build_assembly_query", "customer_query", "currency_query", "customer_type_query", "vendor_query", "item_query", "class_query", "terms_query", "deleted_list_object_query", "deleted_transaction_query", "discount_item_query", "employee_query", "invoice_query", "bill_query", "estimate_query", "inventory_adjustment_query", "inventory_assembly_item_query", "inventory_item_query", "inventory_site_query", "item_group_query", "item_site_query", "non_inventory_item_query", "other_charge_item_query", "other_name_query", "payment_method_query", "payments_to_deposit_query", "payroll_wage_item_query", "preferences_query", "price_level_query", "report_aging_query", "report_budget_summary_query", "report_custom_detail_query", "report_custom_summary_query", "report_general_detail_query", "report_general_summary_query", "report_job_query", "report_payroll_detail_query", "report_payroll_summary_query", "report_time_query", "sales_receipt_query", "sales_representative_query", "sales_tax_code_query", "sales_tax_item_query", "service_item_query", "shipping_method_query", "subtotal_item_query", "purchase_order_query", "sales_order_query", "template_query", "time_tracking_activity_query", "transaction_query", "transfer_query", "unit_of_measure_set_query", "credit_memo_query", "receive_payment_query", "check_query", "deposit_query", "journal_entry_query", "vendor_credit_query", "credit_card_charge_query", "credit_card_credit_query", "credit_card_refund_query", "item_receipt_query", "invoice_add", "bill_add", "qbxml_passthrough" ] }, "idempotencyKey": { "type": "string", "nullable": true }, "submittedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" }, "errorMessage": { "type": "string", "nullable": true }, "qbdFailureKind": { "type": "string", "nullable": true, "enum": [ "quickbooks_revision_conflict", "quickbooks_company_file_mismatch", "quickbooks_empty_qbxml_response", "quickbooks_feature_unavailable", "quickbooks_invalid_list_id", "quickbooks_online_processing_required", "quickbooks_personal_data_permission_required", "quickbooks_read_timeout", "quickbooks_sdk_unavailable", null ] }, "lastQbStatusCode": { "type": "number", "nullable": true }, "lastQbStatusSeverity": { "type": "string", "nullable": true, "enum": [ "info", "warning", "error", "unknown", null ] }, "lastQbStatusMessage": { "type": "string", "nullable": true } }, "required": [ "status", "operationId", "connectionId", "kind", "idempotencyKey", "submittedAt", "completedAt", "errorMessage", "qbdFailureKind", "lastQbStatusCode", "lastQbStatusSeverity", "lastQbStatusMessage" ] }, "CreateQbdOperationRequestDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "company_identity_guard", "company_query", "account_query", "account_tax_line_query", "bill_check_payment_query", "bill_credit_card_payment_query", "bills_to_pay_query", "build_assembly_query", "customer_query", "currency_query", "customer_type_query", "vendor_query", "item_query", "class_query", "terms_query", "deleted_list_object_query", "deleted_transaction_query", "discount_item_query", "employee_query", "invoice_query", "bill_query", "estimate_query", "inventory_adjustment_query", "inventory_assembly_item_query", "inventory_item_query", "inventory_site_query", "item_group_query", "item_site_query", "non_inventory_item_query", "other_charge_item_query", "other_name_query", "payment_method_query", "payments_to_deposit_query", "payroll_wage_item_query", "preferences_query", "price_level_query", "report_aging_query", "report_budget_summary_query", "report_custom_detail_query", "report_custom_summary_query", "report_general_detail_query", "report_general_summary_query", "report_job_query", "report_payroll_detail_query", "report_payroll_summary_query", "report_time_query", "sales_receipt_query", "sales_representative_query", "sales_tax_code_query", "sales_tax_item_query", "service_item_query", "shipping_method_query", "subtotal_item_query", "purchase_order_query", "sales_order_query", "template_query", "time_tracking_activity_query", "transaction_query", "transfer_query", "unit_of_measure_set_query", "credit_memo_query", "receive_payment_query", "check_query", "deposit_query", "journal_entry_query", "vendor_credit_query", "credit_card_charge_query", "credit_card_credit_query", "credit_card_refund_query", "item_receipt_query", "invoice_add", "bill_add", "qbxml_passthrough" ] }, "requestXml": { "type": "string", "minLength": 1 }, "qbdResourceName": { "type": "string", "nullable": true, "enum": [ "account-tax-lines", "accounts", "bill-check-payments", "bill-credit-card-payments", "bills", "bills-to-pay", "build-assemblies", "checks", "classes", "company", "credit-card-charges", "credit-card-credits", "credit-card-refunds", "credit-memos", "currencies", "customer-types", "customers", "date-driven-terms", "deleted-list-objects", "deleted-transactions", "deposits", "discount-items", "employees", "estimates", "inventory-adjustments", "inventory-assembly-items", "inventory-items", "inventory-sites", "invoices", "item-groups", "item-receipts", "item-sites", "journal-entries", "non-inventory-items", "other-charge-items", "other-names", "payment-methods", "payments-to-deposit", "payroll-wage-items", "preferences", "price-levels", "purchase-orders", "receive-payments", "sales-orders", "sales-representatives", "sales-receipts", "sales-tax-codes", "sales-tax-items", "service-items", "shipping-methods", "standard-terms", "subtotal-items", "templates", "time-tracking-activities", "transactions", "transfers", "unit-of-measure-sets", "vendor-credits", "vendors", null ] }, "qbdWriteAction": { "type": "string", "nullable": true, "enum": [ "create", "update", "delete", "void", null ] }, "priority": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 100 ] } ], "default": 50 }, "idempotencyKey": { "type": "string", "nullable": true, "default": null }, "suppressWebhooks": { "type": "boolean" } }, "required": [ "kind", "requestXml" ] }, "QbdCatalogSnapshotDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "enum": [ "company", "account", "account_tax_line", "bill_check_payment", "bill_credit_card_payment", "bills_to_pay", "build_assembly", "customer", "currency", "customer_type", "vendor", "item", "class", "terms", "deleted_list_object", "deleted_transaction", "discount_item", "employee", "invoice", "bill", "estimate", "inventory_adjustment", "inventory_assembly_item", "inventory_item", "inventory_site", "item_group", "item_site", "non_inventory_item", "other_charge_item", "other_name", "payment_method", "payments_to_deposit", "payroll_wage_item", "preferences", "price_level", "report_aging", "report_budget_summary", "report_custom_detail", "report_custom_summary", "report_general_detail", "report_general_summary", "report_job", "report_payroll_detail", "report_payroll_summary", "report_time", "sales_receipt", "sales_representative", "sales_tax_code", "sales_tax_item", "service_item", "shipping_method", "subtotal_item", "purchase_order", "sales_order", "template", "time_tracking_activity", "transaction", "transfer", "unit_of_measure_set", "credit_memo", "receive_payment", "check", "deposit", "journal_entry", "vendor_credit", "credit_card_charge", "credit_card_credit", "credit_card_refund", "item_receipt" ] }, "externalId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" }, "rawXmlObjectKey": { "type": "string", "nullable": true }, "sourceHash": { "type": "string", "nullable": true }, "data": { "type": "object", "additionalProperties": { "nullable": true } }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "connectionId", "entityType", "externalId", "name", "isActive", "rawXmlObjectKey", "sourceHash", "data", "updatedAt" ] }, "QbdCatalogListResponseDto": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 } }, "required": [ "snapshots", "nextKey", "remainingCount" ] }, "QbdCatalogRefreshDto": { "type": "object", "properties": { "refreshId": { "type": "string", "minLength": 1 }, "generationId": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "enum": [ "company", "account", "account_tax_line", "bill_check_payment", "bill_credit_card_payment", "bills_to_pay", "build_assembly", "customer", "currency", "customer_type", "vendor", "item", "class", "terms", "deleted_list_object", "deleted_transaction", "discount_item", "employee", "invoice", "bill", "estimate", "inventory_adjustment", "inventory_assembly_item", "inventory_item", "inventory_site", "item_group", "item_site", "non_inventory_item", "other_charge_item", "other_name", "payment_method", "payments_to_deposit", "payroll_wage_item", "preferences", "price_level", "report_aging", "report_budget_summary", "report_custom_detail", "report_custom_summary", "report_general_detail", "report_general_summary", "report_job", "report_payroll_detail", "report_payroll_summary", "report_time", "sales_receipt", "sales_representative", "sales_tax_code", "sales_tax_item", "service_item", "shipping_method", "subtotal_item", "purchase_order", "sales_order", "template", "time_tracking_activity", "transaction", "transfer", "unit_of_measure_set", "credit_memo", "receive_payment", "check", "deposit", "journal_entry", "vendor_credit", "credit_card_charge", "credit_card_credit", "credit_card_refund", "item_receipt" ] }, "reason": { "type": "string", "enum": [ "read_through", "scheduled_prewarm", "scheduled_webhook" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "operationId": { "type": "string", "nullable": true }, "recordCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" }, "dataAsOf": { "type": "string", "nullable": true, "format": "date-time" }, "errorMessage": { "type": "string", "nullable": true } }, "required": [ "refreshId", "generationId", "entityType", "reason", "status", "operationId", "recordCount", "createdAt", "startedAt", "completedAt", "dataAsOf", "errorMessage" ] }, "QbdCatalogRefreshAcceptedDto": { "type": "object", "properties": { "refresh": { "$ref": "#/components/schemas/QbdCatalogRefreshDto" }, "retryAfterSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "refresh", "retryAfterSeconds" ] }, "QbdSnapshotErrorDto": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "refresh": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshDto" }, { "nullable": true } ] } }, "required": [ "refresh" ] } ] }, "QbdApiCatalogListResponseDto": { "type": "object", "properties": { "objectType": { "type": "string", "enum": [ "list" ] }, "url": { "type": "string", "minLength": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } }, "nextCursor": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "objectType", "url", "data", "nextCursor", "remainingCount", "hasMore" ] }, "QbdMirrorReadMetadata": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "mirror" ] }, "generationId": { "type": "string", "minLength": 1 }, "policyRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "resourceType": { "type": "string", "enum": [ "customer", "vendor", "service_item", "inventory_item", "non_inventory_item", "other_charge_item", "discount_item", "subtotal_item", "inventory_assembly_item", "item_group", "account", "class", "terms", "invoice", "bill", "sales_order", "estimate", "currency", "customer_type", "payment_method", "price_level", "sales_tax_code", "sales_tax_item", "shipping_method", "sales_representative", "unit_of_measure_set" ] }, "status": { "type": "string", "enum": [ "building", "ready", "refreshing", "degraded" ] }, "dataAsOf": { "type": "string", "nullable": true, "format": "date-time" }, "lastSyncedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lagSeconds": { "type": "integer", "nullable": true, "minimum": 0 }, "isStale": { "type": "boolean" }, "syncId": { "type": "string", "minLength": 1 }, "refresh": { "type": "string", "enum": [ "not_requested", "admitted", "coalesced_or_deferred", "unavailable" ] }, "afterOperationId": { "type": "string", "nullable": true }, "projectionStatus": { "type": "string", "enum": [ "not_requested", "pending", "applied" ] } }, "required": [ "source", "generationId", "policyRevision", "resourceType", "status", "dataAsOf", "lastSyncedAt", "lagSeconds", "isStale", "syncId", "refresh", "afterOperationId", "projectionStatus" ] }, "QbdMirrorReadError": { "type": "object", "properties": { "error": { "type": "string" }, "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" }, "parameterName": { "type": "string" } }, "required": [ "error" ] }, "QbdSearchResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "customer", "vendor", "service_item", "inventory_item", "non_inventory_item", "other_charge_item", "discount_item", "subtotal_item", "inventory_assembly_item", "item_group", "account", "class", "terms", "invoice", "bill", "sales_order", "estimate", "currency", "customer_type", "payment_method", "price_level", "sales_tax_code", "sales_tax_item", "shipping_method", "sales_representative", "unit_of_measure_set" ] }, "externalId": { "type": "string", "minLength": 1 }, "generationId": { "type": "string", "minLength": 1 }, "sequence": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "sourceObservedAt": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean" }, "displayName": { "type": "string", "maxLength": 512 }, "companyName": { "type": "string", "maxLength": 256 }, "description": { "type": "string", "maxLength": 512 }, "sku": { "type": "string", "maxLength": 256 }, "isActive": { "type": "boolean" }, "price": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" }, { "nullable": true } ] } }, "required": [ "resourceType", "externalId", "generationId", "sequence", "sourceObservedAt", "deleted", "displayName", "companyName", "description", "sku", "isActive", "price" ] } }, "meta": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "search" ] }, "status": { "type": "string", "enum": [ "building", "ready", "rebuilding" ] }, "generationId": { "type": "string" }, "indexGeneration": { "type": "string", "nullable": true }, "dataAsOf": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "source", "status", "generationId", "indexGeneration", "dataAsOf" ] } }, "required": [ "items", "meta" ] }, "QbdApiWriteRequestDto": { "type": "object", "properties": { "suppressWebhooks": { "type": "boolean" } }, "additionalProperties": { "nullable": true } }, "QbdReferenceDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "fullName": { "type": "string", "nullable": true } }, "required": [ "id", "fullName" ] }, "QbdCustomerAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "line3": { "type": "string", "nullable": true }, "line4": { "type": "string", "nullable": true }, "line5": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "line1", "line2", "line3", "line4", "line5", "city", "state", "postalCode", "country", "note" ] }, "QbdCustomerShippingAddressDto": { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerAddressDto" }, { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "isDefaultShippingAddress": { "type": "boolean", "nullable": true } }, "required": [ "name", "isDefaultShippingAddress" ] } ] }, "QbdCustomerCustomFieldDto": { "type": "object", "properties": { "ownerId": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1 }, "value": { "type": "string", "nullable": true } }, "required": [ "ownerId", "name", "value" ] }, "QbdCustomerAdditionalContactDto": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "revisionNumber": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "parentCustomerId": { "type": "string", "nullable": true }, "salutation": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "middleName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "customContactFields": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCustomerCustomFieldDto" } } }, "required": [ "salutation", "firstName", "middleName", "lastName", "jobTitle", "customContactFields" ] }, "QbdCustomerAdditionalNoteDto": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1 } }, "required": [ "note" ] }, "QbdCustomerCreditCardDto": { "type": "object", "properties": { "number": { "type": "string", "nullable": true }, "expirationMonth": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 }, "expirationYear": { "type": "integer", "nullable": true, "minimum": 1900 }, "name": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true } }, "required": [ "number", "expirationMonth", "expirationYear", "name", "address", "postalCode" ] }, "QbdCustomerResourceDto": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "objectType": { "type": "string", "enum": [ "qbd_customer" ] }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "minLength": 1 }, "revisionNumber": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1 }, "fullName": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" }, "class": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "parent": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "sublevel": { "type": "integer", "minimum": 0 }, "companyName": { "type": "string", "nullable": true }, "salutation": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "middleName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerAddressDto" }, { "nullable": true } ] }, "shippingAddress": { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerAddressDto" }, { "nullable": true } ] }, "alternateShippingAddresses": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/QbdCustomerShippingAddressDto" } }, "phone": { "type": "string", "nullable": true }, "alternatePhone": { "type": "string", "nullable": true }, "fax": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "ccEmail": { "type": "string", "nullable": true }, "contact": { "type": "string", "nullable": true }, "alternateContact": { "type": "string", "nullable": true }, "customContactFields": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCustomerCustomFieldDto" } }, "additionalContacts": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCustomerAdditionalContactDto" } }, "customerType": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "terms": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "salesRepresentative": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "balance": { "type": "string", "nullable": true }, "totalBalance": { "type": "string", "nullable": true }, "salesTaxCode": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "salesTaxItem": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "salesTaxCountry": { "type": "string", "nullable": true, "enum": [ "australia", "canada", "uk", "us", null ] }, "resaleNumber": { "type": "string", "nullable": true }, "accountNumber": { "type": "string", "nullable": true }, "creditLimit": { "type": "string", "nullable": true }, "preferredPaymentMethod": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "creditCard": { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerCreditCardDto" }, { "nullable": true } ] }, "jobStatus": { "type": "string", "nullable": true, "enum": [ "awarded", "closed", "in_progress", "none", "not_awarded", "pending", null ] }, "jobStartDate": { "type": "string", "nullable": true }, "jobProjectedEndDate": { "type": "string", "nullable": true }, "jobEndDate": { "type": "string", "nullable": true }, "jobDescription": { "type": "string", "nullable": true }, "jobType": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "note": { "type": "string", "nullable": true }, "additionalNotes": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCustomerAdditionalNoteDto" } }, "preferredDeliveryMethod": { "type": "string", "nullable": true, "enum": [ "email", "mail", "none", null ] }, "priceLevel": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "externalId": { "type": "string", "nullable": true }, "taxRegistrationNumber": { "type": "string", "nullable": true }, "currency": { "allOf": [ { "$ref": "#/components/schemas/QbdReferenceDto" }, { "nullable": true } ] }, "customFields": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCustomerCustomFieldDto" } } }, "required": [ "id", "objectType", "createdAt", "updatedAt", "revisionNumber", "name", "fullName", "isActive", "class", "parent", "sublevel", "companyName", "salutation", "firstName", "middleName", "lastName", "jobTitle", "billingAddress", "shippingAddress", "alternateShippingAddresses", "phone", "alternatePhone", "fax", "email", "ccEmail", "contact", "alternateContact", "customContactFields", "additionalContacts", "customerType", "terms", "salesRepresentative", "balance", "totalBalance", "salesTaxCode", "salesTaxItem", "salesTaxCountry", "resaleNumber", "accountNumber", "creditLimit", "preferredPaymentMethod", "creditCard", "jobStatus", "jobStartDate", "jobProjectedEndDate", "jobEndDate", "jobDescription", "jobType", "note", "additionalNotes", "preferredDeliveryMethod", "priceLevel", "externalId", "taxRegistrationNumber", "currency", "customFields" ] }, "QbdCustomerListResponseDto": { "type": "object", "properties": { "objectType": { "type": "string", "enum": [ "list" ] }, "url": { "type": "string", "minLength": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/QbdCustomerResourceDto" } }, "nextCursor": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "objectType", "url", "data", "nextCursor", "remainingCount", "hasMore" ] }, "QbdSetupSessionDto": { "type": "object", "properties": { "setupSessionId": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "canceled", "expired" ] }, "setupUrl": { "type": "string", "minLength": 1 }, "callback": { "allOf": [ { "$ref": "#/components/schemas/QbdSetupCallbackDto" }, { "nullable": true } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "setupSessionId", "accountId", "projectId", "connectionId", "status", "setupUrl", "callback", "expiresAt", "createdAt" ] }, "QbdSetupSessionCreatedDto": { "type": "object", "properties": { "setupSession": { "$ref": "#/components/schemas/QbdSetupSessionDto" }, "setupUrl": { "type": "string", "minLength": 1 } }, "required": [ "setupSession", "setupUrl" ] }, "CreateQbdSetupSessionRequestDto": { "type": "object", "properties": { "ttlSeconds": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true, "maximum": 14400 }, "callback": { "allOf": [ { "$ref": "#/components/schemas/QbdSetupCallbackDto" }, { "nullable": true } ] } } }, "QbdSetupSessionConnectionViewDto": { "type": "object", "properties": { "setupSession": { "$ref": "#/components/schemas/QbdSetupSessionDto" }, "qwcPassword": { "type": "string", "nullable": true } }, "required": [ "setupSession", "qwcPassword" ] }, "QbdSetupSessionViewDto": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/QbdSetupSessionDto" }, "connection": { "$ref": "#/components/schemas/QbdConnectionDto" }, "projectName": { "type": "string", "minLength": 1 }, "branding": { "$ref": "#/components/schemas/BoostConnectAccountBrandingDto" }, "qwcPassword": { "type": "string", "nullable": true } }, "required": [ "session", "connection", "projectName", "branding", "qwcPassword" ] }, "QbdSetupCallbackExchangeRequestDto": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "codeVerifier": { "type": "string", "nullable": true } }, "required": [ "code" ] }, "QbdSetupCallbackExchangeResponseDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "setupSessionId": { "type": "string", "minLength": 1 }, "result": { "type": "string", "enum": [ "connected", "canceled", "expired", "failed" ] }, "state": { "type": "string", "minLength": 1 }, "occurredAt": { "type": "string", "format": "date-time" }, "redeemedAt": { "type": "string", "format": "date-time" }, "errorMessage": { "type": "string", "nullable": true } }, "required": [ "accountId", "projectId", "connectionId", "setupSessionId", "result", "state", "occurredAt", "redeemedAt", "errorMessage" ] }, "BoostConnectWebhookEndpointDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "webhookId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1, "format": "uri", "description": "HTTPS delivery URL without embedded credentials or a URL fragment." }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "mirror.record.created", "mirror.record.updated", "mirror.record.deleted", "mirror.sync.completed", "mirror.sync.failed", "connection.status.changed", "catalog.sync.completed", "operation.completed", "operation.failed", "qbd.entity.created", "qbd.entity.updated", "qbd.entity.deleted", "qbd.entity.voided", "qbd.entity.sync.completed", "qbd.entity.sync.failed" ] } }, "resourceNames": { "type": "array", "items": { "type": "string", "enum": [ "account-tax-lines", "accounts", "bill-check-payments", "bill-credit-card-payments", "bills", "bills-to-pay", "build-assemblies", "checks", "classes", "company", "credit-card-charges", "credit-card-credits", "credit-card-refunds", "credit-memos", "currencies", "customer-types", "customers", "date-driven-terms", "deleted-list-objects", "deleted-transactions", "deposits", "discount-items", "employees", "estimates", "inventory-adjustments", "inventory-assembly-items", "inventory-items", "inventory-sites", "invoices", "item-groups", "item-receipts", "item-sites", "journal-entries", "non-inventory-items", "other-charge-items", "other-names", "payment-methods", "payments-to-deposit", "payroll-wage-items", "preferences", "price-levels", "purchase-orders", "receive-payments", "sales-orders", "sales-representatives", "sales-receipts", "sales-tax-codes", "sales-tax-items", "service-items", "shipping-methods", "standard-terms", "subtotal-items", "templates", "time-tracking-activities", "transactions", "transfers", "unit-of-measure-sets", "vendor-credits", "vendors" ] } }, "connectionScope": { "type": "string", "enum": [ "all", "selected" ], "default": "all" }, "connectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "projectId", "webhookId", "url", "status", "eventTypes", "resourceNames", "createdAt", "updatedAt" ] }, "BoostConnectWebhookEndpointCreatedDto": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointDto" }, "signingSecret": { "type": "string", "minLength": 1 } }, "required": [ "webhook", "signingSecret" ] }, "BoostConnectWebhookEndpointListDto": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointDto" } } }, "required": [ "webhooks" ] }, "DeleteBoostConnectWebhookEndpointResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] }, "CreateBoostConnectWebhookEndpointRequestDto": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "format": "uri", "description": "HTTPS delivery URL without embedded credentials or a URL fragment." }, "eventTypes": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "mirror.record.created", "mirror.record.updated", "mirror.record.deleted", "mirror.sync.completed", "mirror.sync.failed", "connection.status.changed", "catalog.sync.completed", "operation.completed", "operation.failed", "qbd.entity.created", "qbd.entity.updated", "qbd.entity.deleted", "qbd.entity.voided", "qbd.entity.sync.completed", "qbd.entity.sync.failed" ] } }, "resourceNames": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "account-tax-lines", "accounts", "bill-check-payments", "bill-credit-card-payments", "bills", "bills-to-pay", "build-assemblies", "checks", "classes", "company", "credit-card-charges", "credit-card-credits", "credit-card-refunds", "credit-memos", "currencies", "customer-types", "customers", "date-driven-terms", "deleted-list-objects", "deleted-transactions", "deposits", "discount-items", "employees", "estimates", "inventory-adjustments", "inventory-assembly-items", "inventory-items", "inventory-sites", "invoices", "item-groups", "item-receipts", "item-sites", "journal-entries", "non-inventory-items", "other-charge-items", "other-names", "payment-methods", "payments-to-deposit", "payroll-wage-items", "preferences", "price-levels", "purchase-orders", "receive-payments", "sales-orders", "sales-representatives", "sales-receipts", "sales-tax-codes", "sales-tax-items", "service-items", "shipping-methods", "standard-terms", "subtotal-items", "templates", "time-tracking-activities", "transactions", "transfers", "unit-of-measure-sets", "vendor-credits", "vendors" ] } }, "connectionScope": { "type": "string", "nullable": true, "enum": [ "all", "selected", null ] }, "connectionIds": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } } }, "required": [ "url" ] }, "UpdateBoostConnectWebhookEndpointRequestDto": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "format": "uri", "description": "HTTPS delivery URL without embedded credentials or a URL fragment." }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "mirror.record.created", "mirror.record.updated", "mirror.record.deleted", "mirror.sync.completed", "mirror.sync.failed", "connection.status.changed", "catalog.sync.completed", "operation.completed", "operation.failed", "qbd.entity.created", "qbd.entity.updated", "qbd.entity.deleted", "qbd.entity.voided", "qbd.entity.sync.completed", "qbd.entity.sync.failed" ] } }, "resourceNames": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "account-tax-lines", "accounts", "bill-check-payments", "bill-credit-card-payments", "bills", "bills-to-pay", "build-assemblies", "checks", "classes", "company", "credit-card-charges", "credit-card-credits", "credit-card-refunds", "credit-memos", "currencies", "customer-types", "customers", "date-driven-terms", "deleted-list-objects", "deleted-transactions", "deposits", "discount-items", "employees", "estimates", "inventory-adjustments", "inventory-assembly-items", "inventory-items", "inventory-sites", "invoices", "item-groups", "item-receipts", "item-sites", "journal-entries", "non-inventory-items", "other-charge-items", "other-names", "payment-methods", "payments-to-deposit", "payroll-wage-items", "preferences", "price-levels", "purchase-orders", "receive-payments", "sales-orders", "sales-representatives", "sales-receipts", "sales-tax-codes", "sales-tax-items", "service-items", "shipping-methods", "standard-terms", "subtotal-items", "templates", "time-tracking-activities", "transactions", "transfers", "unit-of-measure-sets", "vendor-credits", "vendors" ] } }, "connectionScope": { "type": "string", "nullable": true, "enum": [ "all", "selected", null ] }, "connectionIds": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 } } }, "required": [ "url", "status", "eventTypes" ] }, "BoostConnectWebhookEventDto": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "enum": [ "mirror.record.created", "mirror.record.updated", "mirror.record.deleted", "mirror.sync.completed", "mirror.sync.failed", "connection.status.changed", "catalog.sync.completed", "operation.completed", "operation.failed", "qbd.entity.created", "qbd.entity.updated", "qbd.entity.deleted", "qbd.entity.voided", "qbd.entity.sync.completed", "qbd.entity.sync.failed" ] }, "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" }, "resourceName": { "type": "string", "nullable": true, "enum": [ "account-tax-lines", "accounts", "bill-check-payments", "bill-credit-card-payments", "bills", "bills-to-pay", "build-assemblies", "checks", "classes", "company", "credit-card-charges", "credit-card-credits", "credit-card-refunds", "credit-memos", "currencies", "customer-types", "customers", "date-driven-terms", "deleted-list-objects", "deleted-transactions", "deposits", "discount-items", "employees", "estimates", "inventory-adjustments", "inventory-assembly-items", "inventory-items", "inventory-sites", "invoices", "item-groups", "item-receipts", "item-sites", "journal-entries", "non-inventory-items", "other-charge-items", "other-names", "payment-methods", "payments-to-deposit", "payroll-wage-items", "preferences", "price-levels", "purchase-orders", "receive-payments", "sales-orders", "sales-representatives", "sales-receipts", "sales-tax-codes", "sales-tax-items", "service-items", "shipping-methods", "standard-terms", "subtotal-items", "templates", "time-tracking-activities", "transactions", "transfers", "unit-of-measure-sets", "vendor-credits", "vendors", null ] }, "occurredAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "eventId", "eventType", "accountId", "projectId", "connectionId", "connection", "resourceName", "occurredAt", "data" ] }, "QbdWriteLineItemDto": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "quantity": { "type": "number", "nullable": true }, "unitPrice": { "type": "number", "nullable": true }, "amount": { "type": "number", "nullable": true }, "accountExternalId": { "type": "string", "nullable": true }, "itemExternalId": { "type": "string", "nullable": true } }, "required": [ "description", "quantity", "unitPrice", "amount", "accountExternalId", "itemExternalId" ] }, "CreateQbdInvoiceWriteRequestDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1 }, "customerExternalId": { "type": "string", "minLength": 1 }, "refNumber": { "type": "string", "nullable": true }, "txnDate": { "type": "string", "nullable": true }, "memo": { "type": "string", "nullable": true }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/QbdWriteLineItemDto" }, "minItems": 1 }, "suppressWebhooks": { "type": "boolean" } }, "required": [ "idempotencyKey", "customerExternalId", "refNumber", "txnDate", "memo", "lineItems" ] }, "CreateQbdBillWriteRequestDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1 }, "vendorExternalId": { "type": "string", "minLength": 1 }, "refNumber": { "type": "string", "nullable": true }, "txnDate": { "type": "string", "nullable": true }, "memo": { "type": "string", "nullable": true }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/QbdWriteLineItemDto" }, "minItems": 1 }, "suppressWebhooks": { "type": "boolean" } }, "required": [ "idempotencyKey", "vendorExternalId", "refNumber", "txnDate", "memo", "lineItems" ] }, "QbdContactResourceDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "enum": [ "company", "account", "account_tax_line", "bill_check_payment", "bill_credit_card_payment", "bills_to_pay", "build_assembly", "customer", "currency", "customer_type", "vendor", "item", "class", "terms", "deleted_list_object", "deleted_transaction", "discount_item", "employee", "invoice", "bill", "estimate", "inventory_adjustment", "inventory_assembly_item", "inventory_item", "inventory_site", "item_group", "item_site", "non_inventory_item", "other_charge_item", "other_name", "payment_method", "payments_to_deposit", "payroll_wage_item", "preferences", "price_level", "report_aging", "report_budget_summary", "report_custom_detail", "report_custom_summary", "report_general_detail", "report_general_summary", "report_job", "report_payroll_detail", "report_payroll_summary", "report_time", "sales_receipt", "sales_representative", "sales_tax_code", "sales_tax_item", "service_item", "shipping_method", "subtotal_item", "purchase_order", "sales_order", "template", "time_tracking_activity", "transaction", "transfer", "unit_of_measure_set", "credit_memo", "receive_payment", "check", "deposit", "journal_entry", "vendor_credit", "credit_card_charge", "credit_card_credit", "credit_card_refund", "item_receipt" ] }, "externalId": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" }, "sourceHash": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string", "minLength": 1 }, "companyName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "termsName": { "type": "string", "nullable": true } }, "required": [ "accountId", "connectionId", "entityType", "externalId", "isActive", "sourceHash", "updatedAt", "displayName", "companyName", "email", "phone", "address", "termsName" ] }, "QbdAccountingCodeResourceDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "enum": [ "company", "account", "account_tax_line", "bill_check_payment", "bill_credit_card_payment", "bills_to_pay", "build_assembly", "customer", "currency", "customer_type", "vendor", "item", "class", "terms", "deleted_list_object", "deleted_transaction", "discount_item", "employee", "invoice", "bill", "estimate", "inventory_adjustment", "inventory_assembly_item", "inventory_item", "inventory_site", "item_group", "item_site", "non_inventory_item", "other_charge_item", "other_name", "payment_method", "payments_to_deposit", "payroll_wage_item", "preferences", "price_level", "report_aging", "report_budget_summary", "report_custom_detail", "report_custom_summary", "report_general_detail", "report_general_summary", "report_job", "report_payroll_detail", "report_payroll_summary", "report_time", "sales_receipt", "sales_representative", "sales_tax_code", "sales_tax_item", "service_item", "shipping_method", "subtotal_item", "purchase_order", "sales_order", "template", "time_tracking_activity", "transaction", "transfer", "unit_of_measure_set", "credit_memo", "receive_payment", "check", "deposit", "journal_entry", "vendor_credit", "credit_card_charge", "credit_card_credit", "credit_card_refund", "item_receipt" ] }, "externalId": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" }, "sourceHash": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string", "minLength": 1 }, "fullName": { "type": "string", "nullable": true }, "typeName": { "type": "string", "nullable": true } }, "required": [ "accountId", "connectionId", "entityType", "externalId", "isActive", "sourceHash", "updatedAt", "displayName", "fullName", "typeName" ] }, "QbdDocumentResourceDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "enum": [ "company", "account", "account_tax_line", "bill_check_payment", "bill_credit_card_payment", "bills_to_pay", "build_assembly", "customer", "currency", "customer_type", "vendor", "item", "class", "terms", "deleted_list_object", "deleted_transaction", "discount_item", "employee", "invoice", "bill", "estimate", "inventory_adjustment", "inventory_assembly_item", "inventory_item", "inventory_site", "item_group", "item_site", "non_inventory_item", "other_charge_item", "other_name", "payment_method", "payments_to_deposit", "payroll_wage_item", "preferences", "price_level", "report_aging", "report_budget_summary", "report_custom_detail", "report_custom_summary", "report_general_detail", "report_general_summary", "report_job", "report_payroll_detail", "report_payroll_summary", "report_time", "sales_receipt", "sales_representative", "sales_tax_code", "sales_tax_item", "service_item", "shipping_method", "subtotal_item", "purchase_order", "sales_order", "template", "time_tracking_activity", "transaction", "transfer", "unit_of_measure_set", "credit_memo", "receive_payment", "check", "deposit", "journal_entry", "vendor_credit", "credit_card_charge", "credit_card_credit", "credit_card_refund", "item_receipt" ] }, "externalId": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" }, "sourceHash": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string", "minLength": 1 }, "txnDate": { "type": "string", "nullable": true }, "refNumber": { "type": "string", "nullable": true }, "totalAmount": { "type": "number", "nullable": true }, "counterpartyExternalId": { "type": "string", "nullable": true } }, "required": [ "accountId", "connectionId", "entityType", "externalId", "isActive", "sourceHash", "updatedAt", "displayName", "txnDate", "refNumber", "totalAmount", "counterpartyExternalId" ] }, "QbdMirrorConfigurationDto": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "policy": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "resourceTypes": { "type": "array", "items": { "type": "string", "enum": [ "customer", "vendor", "service_item", "inventory_item", "non_inventory_item", "other_charge_item", "discount_item", "subtotal_item", "inventory_assembly_item", "item_group", "account", "class", "terms", "invoice", "bill", "sales_order", "estimate", "currency", "customer_type", "payment_method", "price_level", "sales_tax_code", "sales_tax_item", "shipping_method", "sales_representative", "unit_of_measure_set" ] }, "minItems": 1, "maxItems": 26 }, "fieldPolicyVersion": { "type": "string", "enum": [ "qbd-document-entry-v1", "qbd-native-current-v2" ] }, "refreshTargetSeconds": { "type": "integer", "minimum": 900, "maximum": 86400 }, "reconciliationTargetSeconds": { "type": "integer", "minimum": 86400, "maximum": 604800 } }, "required": [ "enabled", "resourceTypes", "fieldPolicyVersion", "refreshTargetSeconds", "reconciliationTargetSeconds" ], "additionalProperties": false }, "policyRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "generationId": { "type": "string", "minLength": 1 }, "companyFingerprint": { "type": "string", "nullable": true }, "inheritedFromAccount": { "type": "boolean" }, "state": { "type": "string", "enum": [ "disabled", "pending", "ready", "identity_mismatch", "purging" ] }, "disabledAt": { "type": "string", "nullable": true, "format": "date-time" }, "purgeAfter": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "projectId", "connectionId", "policy", "policyRevision", "generationId", "companyFingerprint", "inheritedFromAccount", "state", "disabledAt", "purgeAfter", "createdAt", "updatedAt" ] }, "QbdMirrorSyncStateDto": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "customer", "vendor", "service_item", "inventory_item", "non_inventory_item", "other_charge_item", "discount_item", "subtotal_item", "inventory_assembly_item", "item_group", "account", "class", "terms", "invoice", "bill", "sales_order", "estimate", "currency", "customer_type", "payment_method", "price_level", "sales_tax_code", "sales_tax_item", "shipping_method", "sales_representative", "unit_of_measure_set" ] }, "generationId": { "type": "string", "minLength": 1 }, "policyRevision": { "type": "integer" }, "scanId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "bootstrap", "incremental", "deletions", "reconcile" ] }, "status": { "type": "string", "enum": [ "pending", "running", "ready", "failed" ] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" }, "dataAsOf": { "type": "string", "nullable": true, "format": "date-time" }, "checkpoint": { "type": "string", "nullable": true, "format": "date-time" }, "projectedSequence": { "type": "integer" }, "searchSequence": { "type": "integer" }, "deliveryReadySequence": { "type": "integer" }, "failureCode": { "type": "string", "nullable": true } }, "required": [ "resourceType", "generationId", "policyRevision", "scanId", "mode", "status", "startedAt", "completedAt", "dataAsOf", "checkpoint", "projectedSequence", "searchSequence", "deliveryReadySequence", "failureCode" ] }, "CreateQbdCustomerContactRequest": { "type": "object", "properties": { "revisionNumber": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Current owner customer/job revisionNumber, not the person's revision. Never substitute a newer revision automatically." }, "salutation": { "type": "string", "minLength": 1, "maxLength": 15 }, "firstName": { "type": "string", "minLength": 1, "maxLength": 25 }, "middleName": { "type": "string", "minLength": 1, "maxLength": 5 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 25 }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 41 }, "email": { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "description": "Person's own single email address; native MainEmail, not the owner's Email." }, "phone": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own work phone; native WorkPhone, not the owner's Phone." }, "mobile": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own mobile phone; native Mobile." } }, "required": [ "revisionNumber", "firstName" ], "additionalProperties": false }, "UpdateQbdCustomerContactRequest": { "type": "object", "properties": { "revisionNumber": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Current owner customer/job revisionNumber, not the person's revision. Never substitute a newer revision automatically." }, "salutation": { "type": "string", "minLength": 1, "maxLength": 15 }, "firstName": { "type": "string", "minLength": 1, "maxLength": 25 }, "middleName": { "type": "string", "minLength": 1, "maxLength": 5 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 25 }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 41 }, "email": { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "description": "Person's own single email address; native MainEmail, not the owner's Email." }, "phone": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own work phone; native WorkPhone, not the owner's Phone." }, "mobile": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own mobile phone; native Mobile." }, "contactRevisionNumber": { "type": "string", "minLength": 1, "maxLength": 16, "description": "The person's current EditSequence: mirror contact revisionNumber or write receipt contacts[].revisionNumber. Distinct from the owner revision." } }, "required": [ "revisionNumber", "firstName", "contactRevisionNumber" ], "additionalProperties": false }, "ResourceMirrorMetadata": { "type": "object", "required": [ "source", "generationId", "resourceType", "status", "dataAsOf" ], "properties": { "source": { "type": "string", "enum": [ "mirror" ] }, "generationId": { "type": "string", "minLength": 1, "maxLength": 512 }, "policyRevision": { "type": "integer" }, "resourceType": { "type": "string", "enum": [ "customers", "vendors", "products", "contacts", "sales-orders", "estimates", "invoices" ] }, "status": { "type": "string", "enum": [ "building", "ready", "refreshing", "degraded" ] }, "dataAsOf": { "type": "string", "format": "date-time", "nullable": true }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true }, "isStale": { "type": "boolean" }, "lagSeconds": { "type": "integer", "nullable": true }, "projectionStatus": { "type": "string", "enum": [ "not_requested", "pending", "applied" ] }, "resources": { "type": "array", "items": { "type": "object" } } } }, "ResourceMirrorRecord": { "type": "object", "required": [ "id", "nativeId", "resourceType", "revisionNumber", "createdAt", "updatedAt", "data", "sync" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "nativeId": { "type": "string", "nullable": true }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 512 }, "revisionNumber": { "type": "string", "minLength": 1, "maxLength": 512, "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "name": { "type": "string" }, "fullName": { "type": "string" }, "kind": { "type": "string", "enum": [ "customer", "job" ] }, "parent": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "fullName": { "type": "string", "nullable": true } } }, "owner": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer", "job", "vendor" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "emails": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "communicationFields": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "value": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "description": "The person's own native fields, such as MainEmail, WorkPhone and Mobile. Parent email/phone are not inherited." }, "type": { "type": "string", "enum": [ "service", "inventory", "non_inventory", "inventory_assembly", "other_charge", "group" ] }, "customer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "fullName": { "type": "string", "nullable": true } } }, "transactionDate": { "type": "string", "format": "date", "nullable": true }, "dueDate": { "type": "string", "format": "date", "nullable": true }, "refNumber": { "type": "string", "nullable": true }, "active": { "type": "boolean", "nullable": true }, "isPaid": { "type": "boolean", "nullable": true }, "isPending": { "type": "boolean", "nullable": true }, "isFullyInvoiced": { "type": "boolean", "nullable": true }, "isManuallyClosed": { "type": "boolean", "nullable": true }, "data": { "type": "object", "additionalProperties": true, "description": "Approved resource fields: the confirmed baseline overlaid with outstanding requested changes. Check sync.status before treating values or totals as confirmed QuickBooks results.", "properties": { "Notes": { "type": "string", "description": "Customer/job main note text, preserving line breaks. Not the job description." }, "AdditionalNotesRet": { "description": "Current customer/job additional notes. Native QBXML parsing may return a single object or an array; the main note can also appear here.", "oneOf": [ { "$ref": "#/components/schemas/ResourceMirrorCustomerNote" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResourceMirrorCustomerNote" } } ] }, "JobDesc": { "type": "string", "description": "Job description; distinct from customer/job Notes." } } }, "sync": { "type": "object", "required": [ "status", "writeId", "operationId", "deadlineAt", "error" ], "properties": { "status": { "type": "string", "enum": [ "pending", "confirmed", "failed", "needs_attention" ] }, "writeId": { "type": "string", "nullable": true }, "operationId": { "type": "string", "nullable": true }, "deadlineAt": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Connector-owned associations, not native QuickBooks fields. Empty on historical imports. Survive same-company mirror rebuilds. Contact failure does not change a confirmed document's accounting status." } } }, "ResourceMirrorCustomerNote": { "type": "object", "additionalProperties": false, "properties": { "NoteID": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Native note ID within its customer/job, when supplied." }, "Date": { "type": "string", "description": "Native note date, when supplied; not inferred from dates typed into the note." }, "Note": { "type": "string", "description": "Note text, preserving line breaks." } } }, "ResourceMirrorList": { "type": "object", "required": [ "data", "nextCursor", "hasMore", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceMirrorRecord" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } }, "ResourceMirrorDetail": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ResourceMirrorRecord" }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } }, "PendingWriteReceipt": { "type": "object", "required": [ "writeId", "recordId", "nativeId", "resourceType", "status", "data" ], "properties": { "writeId": { "type": "string" }, "recordId": { "type": "string", "description": "Save this stable, connection/company-scoped identity, not nativeId. Existing native records keep their original ID; new records receive a bcr_ ID." }, "nativeId": { "type": "string", "nullable": true }, "resourceType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "failed", "needs_attention" ] }, "data": { "type": "object", "additionalProperties": true, "description": "Latest effective requested fields. Pending values and calculated totals are not confirmed QuickBooks results." } } }, "TrackedCustomersCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 41, "description": "The case-insensitive name of this customer. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two customers could both have the `name` \"Website Redesign Project\", but they could have unique `fullName` values, such as \"ABC Corporation:Website Redesign Project\" and \"Baker:Website Redesign Project\".\n\nMaximum length: 41 characters.", "example": "Website Redesign Project" }, "isActive": { "description": "Indicates whether this customer is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "classId": { "description": "The customer's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent customer one level above this one in the hierarchy. For example, if this customer has a `fullName` of \"ABC Corporation:Website Redesign Project\", its parent has a `fullName` of \"ABC Corporation\". If this customer is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "companyName": { "description": "The name of the company associated with this customer. This name is used on invoices, checks, and other forms.\n\nMaximum length: 41 characters.", "example": "Acme Corporation", "type": "string", "maxLength": 41 }, "salutation": { "description": "The formal salutation title that precedes the name of the contact person for this customer, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The first name of the contact person for this customer.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The middle name of the contact person for this customer.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The last name of the contact person for this customer.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The job title of the contact person for this customer.", "example": "Purchasing Manager", "type": "string" }, "billingAddress": { "description": "The customer's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The customer's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "alternateShippingAddresses": { "description": "A list of additional shipping addresses for this customer. Useful when the customer has multiple shipping locations.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 41, "description": "The case-insensitive unique name of this shipping address, unique across all shipping addresses.\n\n**NOTE**: Shipping addresses do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.\n\nMaximum length: 41 characters.", "example": "Alternate shipping address" }, "line1": { "description": "The first line of the shipping address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the shipping address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the shipping address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the shipping address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the shipping address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the shipping address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the shipping address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the shipping address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the shipping address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the shipping address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" }, "isDefaultShippingAddress": { "description": "Indicates whether this shipping address is the default shipping address.", "example": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "phone": { "description": "The customer's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "alternatePhone": { "description": "The customer's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The customer's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The customer's email address.", "example": "customer@example.com", "type": "string" }, "ccEmail": { "description": "An email address to carbon copy (CC) on communications with this customer.", "example": "manager@example.com", "type": "string" }, "contact": { "description": "The name of the primary contact person for this customer.", "example": "Jane Smith", "type": "string" }, "alternateContact": { "description": "The name of a alternate contact person for this customer.", "example": "Bob Johnson", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this customer, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "additionalContacts": { "description": "Additional alternate contacts for this customer.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "salutation": { "description": "The contact's formal salutation title that precedes their name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "type": "string", "maxLength": 25, "description": "The contact's first name.\n\nMaximum length: 25 characters.", "example": "John" }, "middleName": { "description": "The contact's middle name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The contact's last name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The contact's job title.", "example": "Purchasing Manager", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this contact, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "firstName" ], "additionalProperties": false } }, "customerTypeId": { "description": "The customer's type, used for categorizing customers into meaningful segments, such as industry or region.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "termsId": { "description": "The customer's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The customer's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "openingBalance": { "description": "The opening balance of this customer's account, indicating the amount owed by this customer, represented as a decimal string.", "example": "1000.00", "type": "string" }, "openingBalanceDate": { "description": "The date of the opening balance of this customer, in ISO 8601 format (YYYY-MM-DD).", "example": "2023-01-01", "type": "string", "format": "date" }, "salesTaxCodeId": { "description": "The default sales-tax code for transactions with this customer, determining whether the transactions are taxable or non-taxable. This can be overridden at the transaction or transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this customer's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCountry": { "description": "The country for which sales tax is collected for this customer.", "example": "us", "type": "string", "enum": [ "australia", "canada", "uk", "us" ] }, "resaleNumber": { "description": "The customer's resale number, used if the customer is purchasing items for resale. This number does not affect sales tax calculations or reports in QuickBooks.", "example": "123456789", "type": "string" }, "accountNumber": { "description": "The customer's account number, which appears in the QuickBooks chart of accounts, reports, and graphs.\n\nNote that if the \"Use Account Numbers\" preference is turned off in QuickBooks, the account number may not be visible in the user interface, but it can still be set and retrieved through the API.", "example": "1010", "type": "string" }, "creditLimit": { "description": "The customer's credit limit, represented as a decimal string. This is the maximum amount of money this customer can spend before being billed. If `null`, there is no credit limit.", "example": "5000.00", "type": "string" }, "preferredPaymentMethodId": { "description": "The customer's preferred payment method (e.g., cash, check, credit card).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditCard": { "description": "The customer's credit card information, including card type, number, and expiration date, used for processing credit card payments.", "type": "object", "properties": { "number": { "description": "The credit card number. Must be masked with lower case \"x\" and no dashes.", "example": "xxxxxxxxxxxx1234", "type": "string" }, "expirationMonth": { "description": "The month when the credit card expires.", "example": 12, "type": "number" }, "expirationYear": { "description": "The year when the credit card expires.", "example": 2024, "type": "number" }, "name": { "description": "The cardholder's name on the card.", "example": "John Doe", "type": "string" }, "address": { "description": "The card's billing address.", "example": "1234 Main St, Anytown, USA, 12345", "type": "string" }, "postalCode": { "description": "The card's billing address ZIP or postal code.", "example": "12345", "type": "string" } }, "additionalProperties": false }, "jobStatus": { "description": "The status of this customer's job, if this object is a job (i.e., sub-customer).", "example": "in_progress", "type": "string", "enum": [ "awarded", "closed", "in_progress", "none", "not_awarded", "pending" ], "default": "none" }, "jobStartDate": { "description": "The date when work on this customer's job began, if applicable, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-15", "type": "string", "format": "date" }, "jobProjectedEndDate": { "description": "The projected completion date for this customer's job, if applicable, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-12-31", "type": "string", "format": "date" }, "jobEndDate": { "description": "The actual completion date of this customer's job, if applicable, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-11-30", "type": "string", "format": "date" }, "jobDescription": { "description": "A brief description of this customer's job, if this object is a job (i.e., sub-customer).", "example": "Kitchen renovation project for residential client.", "type": "string" }, "jobTypeId": { "description": "The type or category of this customer's job, if this object is a job (i.e., sub-customer). Useful for classifying into meaningful segments (e.g., repair, installation, consulting).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "note": { "description": "A note or comment about this customer.", "example": "Our favorite customer.", "type": "string" }, "additionalNotes": { "description": "Additional notes about this customer.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "note": { "type": "string", "description": "The text of this note.", "example": "This is a fun note." } }, "required": [ "note" ], "additionalProperties": false } }, "preferredDeliveryMethod": { "description": "The preferred method for delivering invoices and other documents to this customer.", "example": "email", "type": "string", "enum": [ "email", "mail", "none" ], "default": "none" }, "priceLevelId": { "description": "The customer's custom price level that QuickBooks automatically applies to calculate item rates in new transactions (e.g., invoices, sales receipts, sales orders, and credit memos) for this customer. While applied automatically, this can be overridden when creating individual transactions. Note that transactions will not show the price level itself, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "taxRegistrationNumber": { "description": "The customer's tax registration number, for use in Canada or the UK.", "example": "GB123456789", "type": "string" }, "currencyId": { "description": "The customer's currency. For built-in currencies, the name and code are standard ISO 4217 international values. For user-defined currencies, all values are editable.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "name" ], "additionalProperties": false }, "TrackedCustomersUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the customer object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive name of this customer. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two customers could both have the `name` \"Website Redesign Project\", but they could have unique `fullName` values, such as \"ABC Corporation:Website Redesign Project\" and \"Baker:Website Redesign Project\".\n\nMaximum length: 41 characters.", "example": "Website Redesign Project", "type": "string", "maxLength": 41 }, "isActive": { "description": "Indicates whether this customer is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The customer's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent customer one level above this one in the hierarchy. For example, if this customer has a `fullName` of \"ABC Corporation:Website Redesign Project\", its parent has a `fullName` of \"ABC Corporation\". If this customer is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "companyName": { "description": "The name of the company associated with this customer. This name is used on invoices, checks, and other forms.\n\nMaximum length: 41 characters.", "example": "Acme Corporation", "type": "string", "maxLength": 41 }, "salutation": { "description": "The formal salutation title that precedes the name of the contact person for this customer, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The first name of the contact person for this customer.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The middle name of the contact person for this customer.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The last name of the contact person for this customer.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The job title of the contact person for this customer.", "example": "Purchasing Manager", "type": "string" }, "billingAddress": { "description": "The customer's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The customer's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "alternateShippingAddresses": { "description": "A list of additional shipping addresses for this customer. Useful when the customer has multiple shipping locations.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 41, "description": "The case-insensitive unique name of this shipping address, unique across all shipping addresses.\n\n**NOTE**: Shipping addresses do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.\n\nMaximum length: 41 characters.", "example": "Alternate shipping address" }, "line1": { "description": "The first line of the shipping address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the shipping address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the shipping address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the shipping address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the shipping address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the shipping address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the shipping address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the shipping address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the shipping address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the shipping address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" }, "isDefaultShippingAddress": { "description": "Indicates whether this shipping address is the default shipping address.", "example": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "phone": { "description": "The customer's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "alternatePhone": { "description": "The customer's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The customer's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The customer's email address.", "example": "customer@example.com", "type": "string" }, "ccEmail": { "description": "An email address to carbon copy (CC) on communications with this customer.", "example": "manager@example.com", "type": "string" }, "contact": { "description": "The name of the primary contact person for this customer.", "example": "Jane Smith", "type": "string" }, "alternateContact": { "description": "The name of a alternate contact person for this customer.", "example": "Bob Johnson", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this customer, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "additionalContacts": { "description": "Additional alternate contacts for this customer.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the contact to update.", "example": "80000001-1234567890" }, "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the contact object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "salutation": { "description": "The contact's formal salutation title that precedes their name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The contact's first name.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The contact's middle name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The contact's last name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The contact's job title.", "example": "Purchasing Manager", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this contact, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "id", "revisionNumber" ], "additionalProperties": false } }, "customerTypeId": { "description": "The customer's type, used for categorizing customers into meaningful segments, such as industry or region.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "termsId": { "description": "The customer's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The customer's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The default sales-tax code for transactions with this customer, determining whether the transactions are taxable or non-taxable. This can be overridden at the transaction or transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this customer's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCountry": { "description": "The country for which sales tax is collected for this customer.", "example": "us", "type": "string", "enum": [ "australia", "canada", "uk", "us" ] }, "resaleNumber": { "description": "The customer's resale number, used if the customer is purchasing items for resale. This number does not affect sales tax calculations or reports in QuickBooks.", "example": "123456789", "type": "string" }, "accountNumber": { "description": "The customer's account number, which appears in the QuickBooks chart of accounts, reports, and graphs.\n\nNote that if the \"Use Account Numbers\" preference is turned off in QuickBooks, the account number may not be visible in the user interface, but it can still be set and retrieved through the API.", "example": "1010", "type": "string" }, "creditLimit": { "description": "The customer's credit limit, represented as a decimal string. This is the maximum amount of money this customer can spend before being billed. If `null`, there is no credit limit.", "example": "5000.00", "type": "string" }, "preferredPaymentMethodId": { "description": "The customer's preferred payment method (e.g., cash, check, credit card).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditCard": { "description": "The customer's credit card information, including card type, number, and expiration date, used for processing credit card payments.", "type": "object", "properties": { "number": { "description": "The credit card number. Must be masked with lower case \"x\" and no dashes.", "example": "xxxxxxxxxxxx1234", "type": "string" }, "expirationMonth": { "description": "The month when the credit card expires.", "example": 12, "type": "number" }, "expirationYear": { "description": "The year when the credit card expires.", "example": 2024, "type": "number" }, "name": { "description": "The cardholder's name on the card.", "example": "John Doe", "type": "string" }, "address": { "description": "The card's billing address.", "example": "1234 Main St, Anytown, USA, 12345", "type": "string" }, "postalCode": { "description": "The card's billing address ZIP or postal code.", "example": "12345", "type": "string" } }, "additionalProperties": false }, "jobStatus": { "description": "The status of this customer's job, if this object is a job (i.e., sub-customer).", "example": "in_progress", "type": "string", "enum": [ "awarded", "closed", "in_progress", "none", "not_awarded", "pending" ] }, "jobStartDate": { "description": "The date when work on this customer's job began, if applicable, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-15", "type": "string", "format": "date" }, "jobProjectedEndDate": { "description": "The projected completion date for this customer's job, if applicable, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-12-31", "type": "string", "format": "date" }, "jobEndDate": { "description": "The actual completion date of this customer's job, if applicable, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-11-30", "type": "string", "format": "date" }, "jobDescription": { "description": "A brief description of this customer's job, if this object is a job (i.e., sub-customer).", "example": "Kitchen renovation project for residential client.", "type": "string" }, "jobTypeId": { "description": "The type or category of this customer's job, if this object is a job (i.e., sub-customer). Useful for classifying into meaningful segments (e.g., repair, installation, consulting).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "note": { "description": "A note or comment about this customer.", "example": "Our favorite customer.", "type": "string" }, "additionalNotes": { "description": "Additional notes about this customer.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The ID of the note to update.", "example": 1, "type": "number" }, "note": { "type": "string", "description": "The text of this note.", "example": "This is a fun note." } }, "required": [ "id", "note" ], "additionalProperties": false } }, "preferredDeliveryMethod": { "description": "The preferred method for delivering invoices and other documents to this customer.", "example": "email", "type": "string", "enum": [ "email", "mail", "none" ] }, "priceLevelId": { "description": "The customer's custom price level that QuickBooks automatically applies to calculate item rates in new transactions (e.g., invoices, sales receipts, sales orders, and credit memos) for this customer. While applied automatically, this can be overridden when creating individual transactions. Note that transactions will not show the price level itself, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "taxRegistrationNumber": { "description": "The customer's tax registration number, for use in Canada or the UK.", "example": "GB123456789", "type": "string" }, "currencyId": { "description": "The customer's currency. For built-in currencies, the name and code are standard ISO 4217 international values. For user-defined currencies, all values are editable.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [], "additionalProperties": false }, "TrackedVendorsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 41, "description": "The case-insensitive unique name of this vendor, unique across all vendors.\n\n**NOTE**: Vendors do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc." }, "isActive": { "description": "Indicates whether this vendor is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "classId": { "description": "The vendor's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "companyName": { "description": "The name of the company associated with this vendor. This name is used on invoices, checks, and other forms.\n\nMaximum length: 41 characters.", "example": "Acme Corporation", "type": "string", "maxLength": 41 }, "salutation": { "description": "The formal salutation title that precedes the name of the contact person for this vendor, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The first name of the contact person for this vendor.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The middle name of the contact person for this vendor.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The last name of the contact person for this vendor.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The job title of the contact person for this vendor.", "example": "Purchasing Manager", "type": "string" }, "billingAddress": { "description": "The vendor's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The vendor's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "phone": { "description": "The vendor's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "alternatePhone": { "description": "The vendor's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The vendor's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The vendor's email address.", "example": "vendor@example.com", "type": "string" }, "ccEmail": { "description": "An email address to carbon copy (CC) on communications with this vendor.", "example": "manager@example.com", "type": "string" }, "contact": { "description": "The name of the primary contact person for this vendor.", "example": "Jane Smith", "type": "string" }, "alternateContact": { "description": "The name of a alternate contact person for this vendor.", "example": "Bob Johnson", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this vendor, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "additionalContacts": { "description": "Additional alternate contacts for this vendor.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "salutation": { "description": "The contact's formal salutation title that precedes their name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "type": "string", "maxLength": 25, "description": "The contact's first name.\n\nMaximum length: 25 characters.", "example": "John" }, "middleName": { "description": "The contact's middle name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The contact's last name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The contact's job title.", "example": "Purchasing Manager", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this contact, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "firstName" ], "additionalProperties": false } }, "nameOnCheck": { "description": "The vendor's name as it should appear on checks issued to this vendor.\n\nMaximum length: 41 characters.", "example": "Acme Supplies Ltd.", "type": "string", "maxLength": 41 }, "accountNumber": { "description": "The vendor's account number, which appears in the QuickBooks chart of accounts, reports, and graphs.\n\nNote that if the \"Use Account Numbers\" preference is turned off in QuickBooks, the account number may not be visible in the user interface, but it can still be set and retrieved through the API.", "example": "1010", "type": "string" }, "note": { "description": "A note or comment about this vendor.", "example": "Preferred vendor for office supplies.", "type": "string" }, "additionalNotes": { "description": "Additional notes about this vendor.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "note": { "type": "string", "description": "The text of this note.", "example": "This is a fun note." } }, "required": [ "note" ], "additionalProperties": false } }, "vendorTypeId": { "description": "The vendor's type, used for categorizing vendors into meaningful segments, such as industry or region.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "termsId": { "description": "The vendor's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditLimit": { "description": "The vendor's credit limit, represented as a decimal string. This is the maximum amount of money that can be spent being before billed by this vendor. If `null`, there is no credit limit.", "example": "5000.00", "type": "string" }, "taxIdentificationNumber": { "description": "The vendor's tax identification number (e.g., EIN or SSN).", "example": "12-3456789", "type": "string" }, "isEligibleFor1099": { "description": "Indicates whether this vendor is eligible to receive a 1099 form for tax reporting purposes. When `true`, then the fields `taxId` and `billingAddress` are required.", "example": true, "type": "boolean" }, "openingBalance": { "description": "The opening balance of this vendor's account, indicating the amount owed to this vendor, represented as a decimal string.", "example": "1000.00", "type": "string" }, "openingBalanceDate": { "description": "The date of the opening balance of this vendor, in ISO 8601 format (YYYY-MM-DD).", "example": "2023-01-01", "type": "string", "format": "date" }, "billingRateId": { "description": "The vendor's billing rate, used to override service item rates in time tracking activities.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "salesTaxCodeId": { "description": "The default sales-tax code for transactions with this vendor, determining whether the transactions are taxable or non-taxable. This can be overridden at the transaction or transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCountry": { "description": "The country for which sales tax is collected for this vendor.", "example": "us", "type": "string", "enum": [ "australia", "canada", "uk", "us" ] }, "isSalesTaxAgency": { "description": "Indicates whether this vendor is a sales tax agency.", "example": false, "type": "boolean" }, "salesTaxReturnId": { "description": "The vendor's sales tax return information, used for tracking and reporting sales tax liabilities.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "taxRegistrationNumber": { "description": "The vendor's tax registration number, for use in Canada or the UK.", "example": "GB123456789", "type": "string" }, "reportingPeriod": { "description": "The vendor's tax reporting period, for use in Canada or the UK.", "example": "quarterly", "type": "string", "enum": [ "annual", "monthly", "quarterly" ] }, "isTrackingPurchaseTax": { "description": "Indicates whether tax is tracked on purchases for this vendor, for use in Canada or the UK.", "example": true, "type": "boolean" }, "purchaseTaxAccountId": { "description": "The account used for tracking taxes on purchases for this vendor, for use in Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isTrackingSalesTax": { "description": "Indicates whether tax is tracked on sales for this vendor, for use in Canada or the UK.", "example": true, "type": "boolean" }, "salesTaxAccountId": { "description": "The account used for tracking taxes on sales for this vendor, for use in Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isCompoundingTax": { "description": "Indicates whether tax is charged on top of tax for this vendor, for use in Canada or the UK.", "example": false, "type": "boolean" }, "defaultExpenseAccountIds": { "description": "The expense accounts to prefill when entering bills for this vendor.", "example": [ "80000001-1234567890" ], "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 36 } }, "currencyId": { "description": "The vendor's currency. For built-in currencies, the name and code are standard ISO 4217 international values. For user-defined currencies, all values are editable.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "name" ], "additionalProperties": false }, "TrackedVendorsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the vendor object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive unique name of this vendor, unique across all vendors.\n\n**NOTE**: Vendors do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "isActive": { "description": "Indicates whether this vendor is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The vendor's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "companyName": { "description": "The name of the company associated with this vendor. This name is used on invoices, checks, and other forms.\n\nMaximum length: 41 characters.", "example": "Acme Corporation", "type": "string", "maxLength": 41 }, "salutation": { "description": "The formal salutation title that precedes the name of the contact person for this vendor, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The first name of the contact person for this vendor.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The middle name of the contact person for this vendor.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The last name of the contact person for this vendor.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The job title of the contact person for this vendor.", "example": "Purchasing Manager", "type": "string" }, "billingAddress": { "description": "The vendor's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The vendor's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "phone": { "description": "The vendor's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "alternatePhone": { "description": "The vendor's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The vendor's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The vendor's email address.", "example": "vendor@example.com", "type": "string" }, "ccEmail": { "description": "An email address to carbon copy (CC) on communications with this vendor.", "example": "manager@example.com", "type": "string" }, "contact": { "description": "The name of the primary contact person for this vendor.", "example": "Jane Smith", "type": "string" }, "alternateContact": { "description": "The name of a alternate contact person for this vendor.", "example": "Bob Johnson", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this vendor, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "additionalContacts": { "description": "Additional alternate contacts for this vendor.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the contact to update.", "example": "80000001-1234567890" }, "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the contact object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "salutation": { "description": "The contact's formal salutation title that precedes their name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The contact's first name.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The contact's middle name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The contact's last name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The contact's job title.", "example": "Purchasing Manager", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this contact, such as phone numbers or email addresses.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the contact field (e.g., \"old address\", \"secondary phone\").", "example": "Main Phone" }, "value": { "type": "string", "description": "The value of the contact field.", "example": "555-123-4567" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "id", "revisionNumber" ], "additionalProperties": false } }, "nameOnCheck": { "description": "The vendor's name as it should appear on checks issued to this vendor.\n\nMaximum length: 41 characters.", "example": "Acme Supplies Ltd.", "type": "string", "maxLength": 41 }, "accountNumber": { "description": "The vendor's account number, which appears in the QuickBooks chart of accounts, reports, and graphs.\n\nNote that if the \"Use Account Numbers\" preference is turned off in QuickBooks, the account number may not be visible in the user interface, but it can still be set and retrieved through the API.", "example": "1010", "type": "string" }, "note": { "description": "A note or comment about this vendor.", "example": "Preferred vendor for office supplies.", "type": "string" }, "additionalNotes": { "description": "Additional notes about this vendor.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The ID of the note to update.", "example": 1, "type": "number" }, "note": { "type": "string", "description": "The text of this note.", "example": "This is a fun note." } }, "required": [ "id", "note" ], "additionalProperties": false } }, "vendorTypeId": { "description": "The vendor's type, used for categorizing vendors into meaningful segments, such as industry or region.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "termsId": { "description": "The vendor's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditLimit": { "description": "The vendor's credit limit, represented as a decimal string. This is the maximum amount of money that can be spent being before billed by this vendor. If `null`, there is no credit limit.", "example": "5000.00", "type": "string" }, "taxIdentificationNumber": { "description": "The vendor's tax identification number (e.g., EIN or SSN).", "example": "12-3456789", "type": "string" }, "isEligibleFor1099": { "description": "Indicates whether this vendor is eligible to receive a 1099 form for tax reporting purposes. When `true`, then the fields `taxId` and `billingAddress` are required.", "example": true, "type": "boolean" }, "billingRateId": { "description": "The vendor's billing rate, used to override service item rates in time tracking activities.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The default sales-tax code for transactions with this vendor, determining whether the transactions are taxable or non-taxable. This can be overridden at the transaction or transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCountry": { "description": "The country for which sales tax is collected for this vendor.", "example": "us", "type": "string", "enum": [ "australia", "canada", "uk", "us" ] }, "isSalesTaxAgency": { "description": "Indicates whether this vendor is a sales tax agency.", "example": false, "type": "boolean" }, "salesTaxReturnId": { "description": "The vendor's sales tax return information, used for tracking and reporting sales tax liabilities.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "taxRegistrationNumber": { "description": "The vendor's tax registration number, for use in Canada or the UK.", "example": "GB123456789", "type": "string" }, "reportingPeriod": { "description": "The vendor's tax reporting period, for use in Canada or the UK.", "example": "quarterly", "type": "string", "enum": [ "annual", "monthly", "quarterly" ] }, "isTrackingPurchaseTax": { "description": "Indicates whether tax is tracked on purchases for this vendor, for use in Canada or the UK.", "example": true, "type": "boolean" }, "purchaseTaxAccountId": { "description": "The account used for tracking taxes on purchases for this vendor, for use in Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isTrackingSalesTax": { "description": "Indicates whether tax is tracked on sales for this vendor, for use in Canada or the UK.", "example": true, "type": "boolean" }, "salesTaxAccountId": { "description": "The account used for tracking taxes on sales for this vendor, for use in Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isCompoundingTax": { "description": "Indicates whether tax is charged on top of tax for this vendor, for use in Canada or the UK.", "example": false, "type": "boolean" }, "defaultExpenseAccountIds": { "description": "The expense accounts to prefill when entering bills for this vendor.", "example": [ "80000001-1234567890" ], "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 36 } }, "currencyId": { "description": "The vendor's currency. For built-in currencies, the name and code are standard ISO 4217 international values. For user-defined currencies, all values are editable.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [], "additionalProperties": false }, "TrackedInvoicesCreate": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this invoice.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The invoice's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. A class defined here is automatically used in this invoice's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "receivablesAccountId": { "description": "The Accounts-Receivable (A/R) account to which this invoice is assigned, used to track the amount owed. If omitted, QuickBooks Desktop uses the default A/R account configured in the company file.\n\n**IMPORTANT**: If this invoice is linked to other transactions, this A/R account must match the `receivablesAccount` used in all linked transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this invoice when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this invoice, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this invoice, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user. When left blank in this create request, this field will be left blank in QuickBooks (i.e., it does *not* auto-increment).\n\nMaximum length: 11 characters.", "example": "INV-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The invoice's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The invoice's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "isPending": { "description": "Indicates whether this invoice has not been completed or is in a draft version.", "example": false, "type": "boolean" }, "isFinanceCharge": { "description": "Whether this invoice includes a finance charge. This field is immutable and can only be set during invoice creation.", "example": true, "type": "boolean" }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this invoice. This field is often used to cross-reference the invoice with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The invoice's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this invoice must be paid, in ISO 8601 format (YYYY-MM-DD).\n\n**NOTE**: If `dueDate` is excluded when creating this invoice, QuickBooks might determine the due date according to the terms set for this customer.", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The invoice's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this invoice is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term \"FOB\" for this field, which stands for \"freight on board\". This field is informational and has no accounting implications.\n\nMaximum length: 13 characters.", "example": "San Francisco, CA", "type": "string", "maxLength": 13 }, "shippingDate": { "description": "The date when the products or services for this invoice were shipped or are expected to be shipped, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "shippingMethodId": { "description": "The shipping method used for this invoice, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this invoice's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.\n\nFor invoices, while using this field to specify a single tax item/group that applies uniformly is recommended, complex tax scenarios may require alternative approaches. In such cases, you can set this field to a 0% tax item (conventionally named \"Tax Calculated On Invoice\") and handle tax calculations through line items instead. When using line items for taxes, note that only individual tax items (not tax groups) can be used, subtotals can help apply a tax to multiple items but only the first tax line after a subtotal is calculated automatically (subsequent tax lines require manual amounts), and the rate column will always display the actual tax amount rather than the rate percentage.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this invoice that appears in reports, but not on the invoice. Use `customerMessage` to add a note to this invoice.", "example": "Customer requested rush delivery", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the invoice.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this invoice is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this invoice is included in the queue of documents for QuickBooks to email to the customer.", "example": true, "type": "boolean" }, "salesTaxCodeId": { "description": "The sales-tax code for this invoice, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this invoice. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoices for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Unlike `otherCustomField1` and `otherCustomField2`, which are line item fields, this exists at the transaction level. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this invoice's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).", "example": 1.2345, "type": "number" }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "linkToTransactionIds": { "description": "IDs of existing transactions that you wish to link to this invoice, such as payments applied, credits used, or associated purchase orders. Note that this links entire transactions, not individual transaction lines. If you want to link individual lines in a transaction, instead use the field `linkToTransactionLine` on this invoice's lines, if available.\n\nTransactions can only be linked when creating this invoice and cannot be unlinked later.\n\nYou can use both `linkToTransactionIds` (on this invoice) and `linkToTransactionLine` (on its transaction lines) as long as they do NOT link to the same transaction (otherwise, QuickBooks will return an error). QuickBooks will also return an error if you attempt to link a transaction that is empty or already closed.\n\n**IMPORTANT**: By default, QuickBooks will not return any information about the linked transactions in this endpoint's response even when this request is successful. To see the transactions linked via this field, refetch the invoice and check the `linkedTransactions` response field. If fetching a list of invoices, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 36 } }, "applyCredits": { "description": "Credits to apply to this invoice, reducing its balance. This creates a link between this invoice and the specified credit transactions.\n\n**IMPORTANT**: By default, QuickBooks will not return any information about the linked transactions in this endpoint's response even when this request is successful. To see the transactions linked via this field, refetch the invoice and check the `linkedTransactions` response field. If fetching a list of invoices, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "creditTransactionId": { "type": "string", "maxLength": 36, "description": "The unique identifier of the credit transaction to apply to this transaction, such as a credit memo, vendor credit, or journal-entry credit.", "example": "ABCDEF-1234567890" }, "appliedAmount": { "type": "string", "description": "The amount of the selected credit transaction to apply to this transaction, represented as a decimal string.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "100.00" }, "overrideCreditApplication": { "description": "Indicates whether to override the credit.", "example": false, "default": false, "type": "boolean" } }, "required": [ "creditTransactionId", "appliedAmount" ], "additionalProperties": false } }, "lines": { "description": "The invoice's line items, each representing a single product or service sold.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this invoice line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this invoice line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this invoice line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this invoice line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "rate": { "description": "The price per unit for this invoice line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this invoice line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "priceLevelId": { "description": "The price level applied to this invoice line. This overrides any price level set on the corresponding customer. The resulting invoice line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The invoice line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all invoice lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this invoice line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `rate`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this invoice line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this invoice line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this invoice line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this invoice line. This is used for tracking individual units of serialized inventory items.", "example": "SN1234567890", "type": "string" }, "lotNumber": { "description": "The lot number of the item associated with this invoice line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "serviceDate": { "description": "The date on which the service for this invoice line was or will be performed, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for service items.", "example": "2024-03-15", "type": "string", "format": "date" }, "salesTaxCodeId": { "description": "The sales-tax code for this invoice line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "overrideItemAccountId": { "description": "The account to use for this invoice line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this invoice line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoice lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this invoice line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoice lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this invoice line. Note that this only links to a single transaction line item, not an entire transaction. If you want to link an entire transaction and bring in all its lines, instead use the field `linkToTransactionIds` on the parent transaction, if available. For invoice lines, you can only link to sales orders; QuickBooks does not support linking invoice lines to other transaction types.\n\nTransaction lines can only be linked when creating this invoice line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this invoice line, you cannot use the field `item` on this line (QuickBooks will return an error) because this field brings in all of the item information you need. You can, however, specify whatever `quantity` or `rate` that you want, or any other transaction line element other than `item`.\n\nIf the parent transaction supports the `linkToTransactionIds` field, you can use both `linkToTransactionLine` (on this invoice line) and `linkToTransactionIds` (on its parent transaction) in the same request as long as they do NOT link to the same transaction (otherwise, QuickBooks will return an error). QuickBooks will also return an error if you attempt to link a transaction that is empty or already closed.\n\n**IMPORTANT**: By default, QuickBooks will not return any information about the linked transaction line in this endpoint's response even when this request is successful. To see the transaction line linked via this field, refetch the parent invoice and check the `linkedTransactions` response field. If fetching a list of invoices, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 512, "description": "The ID of the transaction to which to link this transaction.", "example": "123ABC-1234567890" }, "transactionLineId": { "type": "string", "maxLength": 36, "description": "The ID of the transaction line to which to link this transaction.", "example": "456DEF-1234567890" } }, "required": [ "transactionId", "transactionLineId" ], "additionalProperties": false }, "customFields": { "description": "The custom fields for the invoice line object, added as user-defined data extensions, not included in the standard QuickBooks object.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "The identifier of the owner of the custom field, which QuickBooks internally calls a \"data extension\". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always \"0\". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. This API fetches all public custom fields (those with an `ownerId` of \"0\") for all objects.", "example": "0" }, "name": { "type": "string", "description": "The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.", "example": "Customer Rating" }, "value": { "type": "string", "description": "The value of this custom field. The maximum length depends on the field's data type.", "example": "Premium" } }, "required": [ "ownerId", "name", "value" ], "additionalProperties": false } } }, "additionalProperties": false } }, "lineGroups": { "description": "The invoice's line item groups, each representing a predefined set of related items.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The invoice line group's item group, representing a predefined set of items bundled because they are commonly purchased together or grouped for faster entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this invoice line group. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this invoice line group. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "serviceDate": { "description": "The date on which the service for this invoice line group was or will be performed, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for service items.", "example": "2024-03-15", "type": "string", "format": "date" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this invoice line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item group associated with this invoice line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the invoice line group object, added as user-defined data extensions, not included in the standard QuickBooks object.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "The identifier of the owner of the custom field, which QuickBooks internally calls a \"data extension\". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always \"0\". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. This API fetches all public custom fields (those with an `ownerId` of \"0\") for all objects.", "example": "0" }, "name": { "type": "string", "description": "The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.", "example": "Customer Rating" }, "value": { "type": "string", "description": "The value of this custom field. The maximum length depends on the field's data type.", "example": "Premium" } }, "required": [ "ownerId", "name", "value" ], "additionalProperties": false } } }, "required": [ "itemGroupId" ], "additionalProperties": false } }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false }, "TrackedInvoicesUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the invoice object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "customerId": { "description": "The customer or customer-job associated with this invoice.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The invoice's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. A class defined here is automatically used in this invoice's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "receivablesAccountId": { "description": "The Accounts-Receivable (A/R) account to which this invoice is assigned, used to track the amount owed. If omitted, QuickBooks Desktop uses the default A/R account configured in the company file.\n\n**IMPORTANT**: If this invoice is linked to other transactions, this A/R account must match the `receivablesAccount` used in all linked transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this invoice when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this invoice, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this invoice, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.\n\nMaximum length: 11 characters.", "example": "INV-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The invoice's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The invoice's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "isPending": { "description": "Indicates whether this invoice has not been completed or is in a draft version.", "example": false, "type": "boolean" }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this invoice. This field is often used to cross-reference the invoice with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The invoice's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this invoice must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The invoice's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this invoice is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term \"FOB\" for this field, which stands for \"freight on board\". This field is informational and has no accounting implications.\n\nMaximum length: 13 characters.", "example": "San Francisco, CA", "type": "string", "maxLength": 13 }, "shippingDate": { "description": "The date when the products or services for this invoice were shipped or are expected to be shipped, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "shippingMethodId": { "description": "The shipping method used for this invoice, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this invoice's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.\n\nFor invoices, while using this field to specify a single tax item/group that applies uniformly is recommended, complex tax scenarios may require alternative approaches. In such cases, you can set this field to a 0% tax item (conventionally named \"Tax Calculated On Invoice\") and handle tax calculations through line items instead. When using line items for taxes, note that only individual tax items (not tax groups) can be used, subtotals can help apply a tax to multiple items but only the first tax line after a subtotal is calculated automatically (subsequent tax lines require manual amounts), and the rate column will always display the actual tax amount rather than the rate percentage.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this invoice that appears in reports, but not on the invoice. Use `customerMessage` to add a note to this invoice.", "example": "Customer requested rush delivery", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the invoice.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this invoice is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this invoice is included in the queue of documents for QuickBooks to email to the customer.", "example": true, "type": "boolean" }, "salesTaxCodeId": { "description": "The sales-tax code for this invoice, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this invoice. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoices for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Unlike `otherCustomField1` and `otherCustomField2`, which are line item fields, this exists at the transaction level. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this invoice's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).", "example": 1.2345, "type": "number" }, "applyCredits": { "description": "Credits to apply to this invoice, reducing its balance. This creates a link between this invoice and the specified credit transactions. For credit-only applications with no received payment amount, update the invoice using this field.\n\n**IMPORTANT**: By default, QuickBooks will not return any information about the linked transactions in this endpoint's response even when this request is successful. To see the transactions linked via this field, refetch the invoice and check the `linkedTransactions` response field. If fetching a list of invoices, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "creditTransactionId": { "type": "string", "maxLength": 36, "description": "The unique identifier of the credit transaction to apply to this transaction, such as a credit memo, vendor credit, or journal-entry credit.", "example": "ABCDEF-1234567890" }, "appliedAmount": { "type": "string", "description": "The amount of the selected credit transaction to apply to this transaction, represented as a decimal string.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "100.00" }, "overrideCreditApplication": { "description": "Indicates whether to override the credit.", "example": false, "default": false, "type": "boolean" } }, "required": [ "creditTransactionId", "appliedAmount" ], "additionalProperties": false } }, "lines": { "description": "The invoice's line items, each representing a single product or service sold.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line items for the invoice with this array. To keep any existing line items, you must include them in this array even if they have not changed. **Any line items not included will be removed.**\n\n2. To add a new line item, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line items, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing invoice line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new invoice lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this invoice line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this invoice line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this invoice line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this invoice line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this invoice line's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The price per unit for this invoice line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this invoice line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "priceLevelId": { "description": "The price level applied to this invoice line. This overrides any price level set on the corresponding customer. The resulting invoice line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The invoice line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all invoice lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this invoice line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `rate`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this invoice line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this invoice line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this invoice line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this invoice line. This is used for tracking individual units of serialized inventory items.", "example": "SN1234567890", "type": "string" }, "lotNumber": { "description": "The lot number of the item associated with this invoice line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "serviceDate": { "description": "The date on which the service for this invoice line was or will be performed, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for service items.", "example": "2024-03-15", "type": "string", "format": "date" }, "salesTaxCodeId": { "description": "The sales-tax code for this invoice line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "overrideItemAccountId": { "description": "The account to use for this invoice line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this invoice line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoice lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this invoice line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoice lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "lineGroups": { "description": "The invoice's line item groups, each representing a predefined set of related items.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line item groups for the invoice with this array. To keep any existing line item groups, you must include them in this array even if they have not changed. **Any line item groups not included will be removed.**\n\n2. To add a new line item group, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line item groups, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing invoice line group you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new invoice line groups you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The invoice line group's item group, representing a predefined set of items bundled because they are commonly purchased together or grouped for faster entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this invoice line group. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this invoice line group. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this invoice line group's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "lines": { "description": "The invoice line group's line items, each representing a single product or service sold.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line items for the invoice line group with this array. To keep any existing line items, you must include them in this array even if they have not changed. **Any line items not included will be removed.**\n\n2. To add a new line item, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line items, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing invoice line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new invoice lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this invoice line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this invoice line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this invoice line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this invoice line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this invoice line's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The price per unit for this invoice line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this invoice line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "priceLevelId": { "description": "The price level applied to this invoice line. This overrides any price level set on the corresponding customer. The resulting invoice line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The invoice line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all invoice lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this invoice line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `rate`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this invoice line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this invoice line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this invoice line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this invoice line. This is used for tracking individual units of serialized inventory items.", "example": "SN1234567890", "type": "string" }, "lotNumber": { "description": "The lot number of the item associated with this invoice line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "serviceDate": { "description": "The date on which the service for this invoice line was or will be performed, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for service items.", "example": "2024-03-15", "type": "string", "format": "date" }, "salesTaxCodeId": { "description": "The sales-tax code for this invoice line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "overrideItemAccountId": { "description": "The account to use for this invoice line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this invoice line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoice lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this invoice line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all invoice lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } }, "required": [], "additionalProperties": false }, "TrackedSalesOrdersCreate": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this sales order.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The sales order's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. A class defined here is automatically used in this sales order's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this sales order when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this sales order, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this sales order, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user. When left blank in this create request, this field will be left blank in QuickBooks (i.e., it does *not* auto-increment).\n\nMaximum length: 11 characters.", "example": "SO-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The sales order's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The sales order's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this sales order. This field is often used to cross-reference the sales order with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The sales order's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this sales order must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The sales order's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this sales order is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term \"FOB\" for this field, which stands for \"freight on board\". This field is informational and has no accounting implications.\n\nMaximum length: 13 characters.", "example": "San Francisco, CA", "type": "string", "maxLength": 13 }, "shippingDate": { "description": "The date when the products or services for this sales order were shipped or are expected to be shipped, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "shippingMethodId": { "description": "The shipping method used for this sales order, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this sales order's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isManuallyClosed": { "description": "Indicates whether this sales order has been manually marked as closed, even if it has not been invoiced.", "example": true, "default": false, "type": "boolean" }, "memo": { "description": "A memo or note for this sales order.", "example": "Customer requested rush delivery", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the sales order.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this sales order is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this sales order is included in the queue of documents for QuickBooks to email to the customer.", "example": true, "type": "boolean" }, "salesTaxCodeId": { "description": "The sales-tax code for this sales order, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this sales order. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales orders for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Unlike `otherCustomField1` and `otherCustomField2`, which are line item fields, this exists at the transaction level. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this sales order's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).", "example": 1.2345, "type": "number" }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "lines": { "description": "The sales order's line items, each representing a single product or service ordered.\n\n**IMPORTANT**: You must specify `lines`, `lineGroups`, or both when creating a sales order.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this sales order line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this sales order line.", "example": "Widget Model X100 - Blue", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this sales order line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this sales order line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "rate": { "description": "The price per unit for this sales order line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this sales order line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "priceLevelId": { "description": "The price level applied to this sales order line. This overrides any price level set on the corresponding customer. The resulting sales order line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The sales order line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all sales order lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this sales order line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `rate`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this sales order line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this sales order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this sales order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this sales order line. This is used for tracking individual units of serialized inventory items.", "example": "SN1234567890", "type": "string" }, "lotNumber": { "description": "The lot number of the item associated with this sales order line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this sales order line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isManuallyClosed": { "description": "Indicates whether this sales order line has been manually marked as closed, even if it has not been invoiced.", "example": true, "default": false, "type": "boolean" }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this sales order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales order lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this sales order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales order lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" }, "customFields": { "description": "The custom fields for the sales order line object, added as user-defined data extensions, not included in the standard QuickBooks object.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "The identifier of the owner of the custom field, which QuickBooks internally calls a \"data extension\". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always \"0\". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. This API fetches all public custom fields (those with an `ownerId` of \"0\") for all objects.", "example": "0" }, "name": { "type": "string", "description": "The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.", "example": "Customer Rating" }, "value": { "type": "string", "description": "The value of this custom field. The maximum length depends on the field's data type.", "example": "Premium" } }, "required": [ "ownerId", "name", "value" ], "additionalProperties": false } } }, "additionalProperties": false } }, "lineGroups": { "description": "The sales order's line item groups, each representing a predefined set of related items.\n\n**IMPORTANT**: You must specify `lines`, `lineGroups`, or both when creating a sales order.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The sales order line group's item group, representing a predefined set of items bundled because they are commonly purchased together or grouped for faster entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this sales order line group. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this sales order line group. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this sales order line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item group associated with this sales order line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the sales order line group object, added as user-defined data extensions, not included in the standard QuickBooks object.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "The identifier of the owner of the custom field, which QuickBooks internally calls a \"data extension\". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always \"0\". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. This API fetches all public custom fields (those with an `ownerId` of \"0\") for all objects.", "example": "0" }, "name": { "type": "string", "description": "The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.", "example": "Customer Rating" }, "value": { "type": "string", "description": "The value of this custom field. The maximum length depends on the field's data type.", "example": "Premium" } }, "required": [ "ownerId", "name", "value" ], "additionalProperties": false } } }, "required": [ "itemGroupId" ], "additionalProperties": false } }, "salesChannelName": { "description": "The type of the sales channel for this sales order.", "example": "ecommerce", "type": "string", "enum": [ "blank", "ecommerce" ] }, "salesStoreName": { "description": "The name of the sales store for this sales order.", "example": "Store 1", "type": "string" }, "salesStoreType": { "description": "The type of the sales store for this sales order.", "example": "Retail", "type": "string" }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false }, "TrackedSalesOrdersUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the sales order object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "customerId": { "description": "The customer or customer-job associated with this sales order.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The sales order's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. A class defined here is automatically used in this sales order's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this sales order when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this sales order, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this sales order, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.\n\nMaximum length: 11 characters.", "example": "SO-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The sales order's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The sales order's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this sales order. This field is often used to cross-reference the sales order with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The sales order's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this sales order must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The sales order's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this sales order is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term \"FOB\" for this field, which stands for \"freight on board\". This field is informational and has no accounting implications.\n\nMaximum length: 13 characters.", "example": "San Francisco, CA", "type": "string", "maxLength": 13 }, "shippingDate": { "description": "The date when the products or services for this sales order were shipped or are expected to be shipped, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "shippingMethodId": { "description": "The shipping method used for this sales order, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this sales order's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isManuallyClosed": { "description": "Indicates whether this sales order has been manually marked as closed, even if it has not been invoiced.", "example": true, "type": "boolean" }, "memo": { "description": "A memo or note for this sales order.", "example": "Customer requested rush delivery", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the sales order.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this sales order is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this sales order is included in the queue of documents for QuickBooks to email to the customer.", "example": true, "type": "boolean" }, "salesTaxCodeId": { "description": "The sales-tax code for this sales order, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this sales order. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales orders for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Unlike `otherCustomField1` and `otherCustomField2`, which are line item fields, this exists at the transaction level. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this sales order's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).", "example": 1.2345, "type": "number" }, "lines": { "description": "The sales order's line items, each representing a single product or service ordered.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line items for the sales order with this array. To keep any existing line items, you must include them in this array even if they have not changed. **Any line items not included will be removed.**\n\n2. To add a new line item, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line items, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing sales order line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new sales order lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this sales order line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this sales order line.", "example": "Widget Model X100 - Blue", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this sales order line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this sales order line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this sales order line's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The price per unit for this sales order line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this sales order line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "priceLevelId": { "description": "The price level applied to this sales order line. This overrides any price level set on the corresponding customer. The resulting sales order line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The sales order line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all sales order lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this sales order line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `rate`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this sales order line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this sales order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this sales order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this sales order line. This is used for tracking individual units of serialized inventory items.", "example": "SN1234567890", "type": "string" }, "lotNumber": { "description": "The lot number of the item associated with this sales order line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this sales order line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isManuallyClosed": { "description": "Indicates whether this sales order line has been manually marked as closed, even if it has not been invoiced.", "example": true, "type": "boolean" }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this sales order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales order lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this sales order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales order lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "lineGroups": { "description": "The sales order's line item groups, each representing a predefined set of related items.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line item groups for the sales order with this array. To keep any existing line item groups, you must include them in this array even if they have not changed. **Any line item groups not included will be removed.**\n\n2. To add a new line item group, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line item groups, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing sales order line group you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new sales order line groups you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The sales order line group's item group, representing a predefined set of items bundled because they are commonly purchased together or grouped for faster entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this sales order line group. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this sales order line group. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this sales order line group's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "lines": { "description": "The sales order line group's line items, each representing a single product or service ordered.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line items for the sales order line group with this array. To keep any existing line items, you must include them in this array even if they have not changed. **Any line items not included will be removed.**\n\n2. To add a new line item, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line items, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing sales order line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new sales order lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this sales order line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this sales order line.", "example": "Widget Model X100 - Blue", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this sales order line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this sales order line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this sales order line's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The price per unit for this sales order line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this sales order line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "priceLevelId": { "description": "The price level applied to this sales order line. This overrides any price level set on the corresponding customer. The resulting sales order line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The sales order line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all sales order lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this sales order line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `rate`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this sales order line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this sales order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this sales order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this sales order line. This is used for tracking individual units of serialized inventory items.", "example": "SN1234567890", "type": "string" }, "lotNumber": { "description": "The lot number of the item associated with this sales order line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this sales order line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isManuallyClosed": { "description": "Indicates whether this sales order line has been manually marked as closed, even if it has not been invoiced.", "example": true, "type": "boolean" }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this sales order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales order lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this sales order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales order lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "salesChannelName": { "description": "The type of the sales channel for this sales order.", "example": "ecommerce", "type": "string", "enum": [ "blank", "ecommerce" ] }, "salesStoreName": { "description": "The name of the sales store for this sales order.", "example": "Store 1", "type": "string" }, "salesStoreType": { "description": "The type of the sales store for this sales order.", "example": "Retail", "type": "string" }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } }, "required": [], "additionalProperties": false }, "TrackedEstimatesCreate": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this estimate.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The estimate's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. A class defined here is automatically used in this estimate's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this estimate when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this estimate, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this estimate, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user. When left blank in this create request, this field will be left blank in QuickBooks (i.e., it does *not* auto-increment).\n\nMaximum length: 11 characters.", "example": "EST-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The estimate's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The estimate's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this estimate is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this estimate. This field is often used to cross-reference the estimate with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The estimate's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this estimate must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The estimate's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this estimate is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term \"FOB\" for this field, which stands for \"freight on board\". This field is informational and has no accounting implications.\n\nMaximum length: 13 characters.", "example": "San Francisco, CA", "type": "string", "maxLength": 13 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this estimate's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this estimate that appears in reports, but not on the estimate. Use `customerMessage` to add a note to this estimate.", "example": "Proposal for website redesign", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the estimate.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForEmail": { "description": "Indicates whether this estimate is included in the queue of documents for QuickBooks to email to the customer.", "example": true, "type": "boolean" }, "salesTaxCodeId": { "description": "The sales-tax code for this estimate, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this estimate. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimates for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Unlike `otherCustomField1` and `otherCustomField2`, which are line item fields, this exists at the transaction level. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this estimate's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).", "example": 1.2345, "type": "number" }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "lines": { "description": "The estimate's line items, each representing a single product or service quoted.\n\n**IMPORTANT**: You must specify `lines`, `lineGroups`, or both when creating an estimate.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this estimate line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this estimate line.", "example": "Graphic illustrations for website redesign", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this estimate line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this estimate line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "rate": { "description": "The price per unit for this estimate line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this estimate line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "classId": { "description": "The estimate line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all estimate lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this estimate line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will calculate `amount` using the rate and any markup you supply. The calculation is `amount = (quantity * rate) * (1 + markupRate)` when `markupRate` is provided, or `amount = (quantity * rate) * (1 + markupRatePercent/100)` when `markupRatePercent` is provided. If `amount`, `rate`, and `quantity` are all unspecified, QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this estimate line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this estimate line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this estimate line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this estimate line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "markupRate": { "description": "The markup that will be passed on to the customer for this item on this estimate line. `amount = (quantity * rate) * (1 + markupRate)`", "example": "0.2", "type": "string" }, "markupRatePercent": { "description": "The markup, expressed as a percentage, that will be passed on to the customer for this item on this estimate line. `amount = (quantity * rate) * (1 + markupRatePercent/100)`", "example": "20.0", "type": "string" }, "priceLevelId": { "description": "The price level applied to this estimate line. This overrides any price level set on the corresponding customer. The resulting estimate line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "overrideItemAccountId": { "description": "The account to use for this estimate line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this estimate line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimate lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this estimate line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimate lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" }, "customFields": { "description": "The custom fields for the estimate line object, added as user-defined data extensions, not included in the standard QuickBooks object.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "The identifier of the owner of the custom field, which QuickBooks internally calls a \"data extension\". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always \"0\". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. This API fetches all public custom fields (those with an `ownerId` of \"0\") for all objects.", "example": "0" }, "name": { "type": "string", "description": "The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.", "example": "Customer Rating" }, "value": { "type": "string", "description": "The value of this custom field. The maximum length depends on the field's data type.", "example": "Premium" } }, "required": [ "ownerId", "name", "value" ], "additionalProperties": false } } }, "additionalProperties": false } }, "lineGroups": { "description": "The estimate's line item groups, each representing a predefined set of related items.\n\n**IMPORTANT**: You must specify `lines`, `lineGroups`, or both when creating an estimate.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The estimate line group's item group, representing a predefined set of items bundled because they are commonly purchased together or grouped for faster entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this estimate line group. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this estimate line group. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this estimate line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item group associated with this estimate line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the estimate line group object, added as user-defined data extensions, not included in the standard QuickBooks object.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ownerId": { "type": "string", "description": "The identifier of the owner of the custom field, which QuickBooks internally calls a \"data extension\". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always \"0\". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. This API fetches all public custom fields (those with an `ownerId` of \"0\") for all objects.", "example": "0" }, "name": { "type": "string", "description": "The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.", "example": "Customer Rating" }, "value": { "type": "string", "description": "The value of this custom field. The maximum length depends on the field's data type.", "example": "Premium" } }, "required": [ "ownerId", "name", "value" ], "additionalProperties": false } } }, "required": [ "itemGroupId" ], "additionalProperties": false } }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false }, "TrackedEstimatesUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the estimate object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "customerId": { "description": "The customer or customer-job associated with this estimate.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The estimate's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. A class defined here is automatically used in this estimate's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this estimate when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this estimate, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this estimate, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.\n\nMaximum length: 11 characters.", "example": "EST-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The estimate's billing address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "shippingAddress": { "description": "The estimate's shipping address.", "type": "object", "properties": { "line1": { "description": "The first line of the address (e.g., street, PO Box, or company name).\n\nMaximum length: 41 characters.", "example": "Acme Supplies Inc.", "type": "string", "maxLength": 41 }, "line2": { "description": "The second line of the address, if needed (e.g., apartment, suite, unit, or building).\n\nMaximum length: 41 characters.", "example": "540 Market St.", "type": "string", "maxLength": 41 }, "line3": { "description": "The third line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "city": { "description": "The city, district, suburb, town, or village name of the address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the address.", "example": "United States", "type": "string" }, "note": { "description": "A note written at the bottom of the address in the form in which it appears, such as the invoice form.", "example": "Main Office", "type": "string" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this estimate is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "createChangeOrder": { "description": "When `true`, creates a \"change order\" that appears in this estimate's description field in QuickBooks's estimate form, specifying exactly what changed in this update request, the dollar amount of each change, and the net dollar change to this estimate.", "example": false, "type": "boolean" }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this estimate. This field is often used to cross-reference the estimate with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The estimate's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this estimate must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The estimate's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this estimate is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term \"FOB\" for this field, which stands for \"freight on board\". This field is informational and has no accounting implications.\n\nMaximum length: 13 characters.", "example": "San Francisco, CA", "type": "string", "maxLength": 13 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this estimate's transactions by applying a specific tax rate collected for a single tax agency. Unlike `salesTaxCode`, which only indicates general taxability, this field drives the actual tax calculation and reporting.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this estimate that appears in reports, but not on the estimate. Use `customerMessage` to add a note to this estimate.", "example": "Proposal for website redesign", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the estimate.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForEmail": { "description": "Indicates whether this estimate is included in the queue of documents for QuickBooks to email to the customer.", "example": true, "type": "boolean" }, "salesTaxCodeId": { "description": "The sales-tax code for this estimate, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this estimate. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimates for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Unlike `otherCustomField1` and `otherCustomField2`, which are line item fields, this exists at the transaction level. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this estimate's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).", "example": 1.2345, "type": "number" }, "lines": { "description": "The estimate's line items, each representing a single product or service quoted.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line items for the estimate with this array. To keep any existing line items, you must include them in this array even if they have not changed. **Any line items not included will be removed.**\n\n2. To add a new line item, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line items, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing estimate line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new estimate lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this estimate line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this estimate line.", "example": "Graphic illustrations for website redesign", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this estimate line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this estimate line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this estimate line's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The price per unit for this estimate line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this estimate line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "classId": { "description": "The estimate line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all estimate lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this estimate line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will calculate `amount` using the rate and any markup you supply. The calculation is `amount = (quantity * rate) * (1 + markupRate)` when `markupRate` is provided, or `amount = (quantity * rate) * (1 + markupRatePercent/100)` when `markupRatePercent` is provided. If `amount`, `rate`, and `quantity` are all unspecified, QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this estimate line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this estimate line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this estimate line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this estimate line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "markupRate": { "description": "The markup that will be passed on to the customer for this item on this estimate line. `amount = (quantity * rate) * (1 + markupRate)`", "example": "0.2", "type": "string" }, "markupRatePercent": { "description": "The markup, expressed as a percentage, that will be passed on to the customer for this item on this estimate line. `amount = (quantity * rate) * (1 + markupRatePercent/100)`", "example": "20.0", "type": "string" }, "priceLevelId": { "description": "The price level applied to this estimate line. This overrides any price level set on the corresponding customer. The resulting estimate line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this estimate line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimate lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this estimate line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimate lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "lineGroups": { "description": "The estimate's line item groups, each representing a predefined set of related items.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line item groups for the estimate with this array. To keep any existing line item groups, you must include them in this array even if they have not changed. **Any line item groups not included will be removed.**\n\n2. To add a new line item group, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line item groups, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing estimate line group you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new estimate line groups you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The estimate line group's item group, representing a predefined set of items bundled because they are commonly purchased together or grouped for faster entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this estimate line group. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this estimate line group. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this estimate line group's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "lines": { "description": "The estimate line group's line items, each representing a single product or service quoted.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing line items for the estimate line group with this array. To keep any existing line items, you must include them in this array even if they have not changed. **Any line items not included will be removed.**\n\n2. To add a new line item, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any line items, omit this field entirely to keep them unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing estimate line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new estimate lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this estimate line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "description": { "description": "A description of this estimate line.", "example": "Graphic illustrations for website redesign", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this estimate line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this estimate line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this estimate line's `unitOfMeasure` field (e.g., \"pound\" or \"kilogram\"). This allows you to select units from a different set than the item's default unit-of-measure set, which remains unchanged on the item itself. The override applies only to this specific line. For example, you can sell an item typically measured in volume units using weight units in a specific transaction by specifying a different unit-of-measure set with this field.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The price per unit for this estimate line. If both `rate` and `amount` are specified, `rate` will be ignored. If both `quantity` and `amount` are specified but not `rate`, QuickBooks will use them to calculate `rate`. Represented as a decimal string. This field cannot be cleared.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "10.00", "type": "string" }, "ratePercent": { "description": "The price of this estimate line expressed as a percentage. Typically used for discount or markup items.", "example": "10.5", "type": "string" }, "classId": { "description": "The estimate line's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default. If a class is specified for the entire parent transaction, it is automatically applied to all estimate lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this estimate line, represented as a decimal string. If both `quantity` and `rate` are specified but not `amount`, QuickBooks will calculate `amount` using the rate and any markup you supply. The calculation is `amount = (quantity * rate) * (1 + markupRate)` when `markupRate` is provided, or `amount = (quantity * rate) * (1 + markupRatePercent/100)` when `markupRatePercent` is provided. If `amount`, `rate`, and `quantity` are all unspecified, QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `rate`. This field cannot be cleared.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "priceRuleConflictStrategy": { "description": "Specifies how to resolve price rule conflicts when adding or modifying this estimate line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this estimate line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this estimate line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this estimate line, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the parent transaction or the associated item.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "markupRate": { "description": "The markup that will be passed on to the customer for this item on this estimate line. `amount = (quantity * rate) * (1 + markupRate)`", "example": "0.2", "type": "string" }, "markupRatePercent": { "description": "The markup, expressed as a percentage, that will be passed on to the customer for this item on this estimate line. `amount = (quantity * rate) * (1 + markupRatePercent/100)`", "example": "20.0", "type": "string" }, "priceLevelId": { "description": "The price level applied to this estimate line. This overrides any price level set on the corresponding customer. The resulting estimate line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this estimate line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimate lines for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Special handling required", "type": "string" }, "otherCustomField2": { "description": "A second built-in custom field for additional information specific to this estimate line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all estimate lines for convenience. Like `otherCustomField1`, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.", "example": "Always ship with a spare", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } }, "required": [], "additionalProperties": false }, "TrackedServiceItemsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this service item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two service items could both have the `name` \"Web-Design\", but they could have unique `fullName` values, such as \"Consulting:Web-Design\" and \"Contracting:Web-Design\".\n\nMaximum length: 31 characters.", "example": "Web-Design" }, "barcode": { "description": "The service item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this service item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "classId": { "description": "The service item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent service item one level above this one in the hierarchy. For example, if this service item has a `fullName` of \"Consulting:Web-Design\", its parent has a `fullName` of \"Consulting\". If this service item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this service item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The default sales-tax code for this service item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesOrPurchaseDetails": { "description": "Details for service items that are exclusively sold or exclusively purchased, but not both. This typically applies to non-inventory items (like a purchased office supply that isn't resold) or service items (like consulting services that are sold but not purchased).\n\n**IMPORTANT**: You must specify either `salesOrPurchaseDetails` or `salesAndPurchaseDetails` when creating a service item, but never both because an item cannot have both configurations.", "type": "object", "properties": { "description": { "description": "A description of this item.", "example": "Hourly Consulting Service", "type": "string" }, "price": { "description": "The price at which this item is purchased or sold, represented as a decimal string.", "example": "19.99", "type": "string" }, "pricePercentage": { "description": "The price of this item expressed as a percentage, used instead of `price` when the item's cost is calculated as a percentage of another amount. For example, a service item that costs a percentage of another item's price.", "example": "10.5", "type": "string" }, "postingAccountId": { "description": "The posting account to which transactions involving this item are posted. This could be an income account when selling or an expense account when purchasing.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "postingAccountId" ], "additionalProperties": false }, "salesAndPurchaseDetails": { "description": "Details for service items that are both purchased and sold, such as reimbursable expenses or inventory items that are bought from vendors and sold to customers.\n\n**IMPORTANT**: You must specify either `salesAndPurchaseDetails` or `salesOrPurchaseDetails` when creating a service item, but never both because an item cannot have both configurations.", "type": "object", "properties": { "salesDescription": { "description": "The description of this item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "expenseAccountId": { "description": "The expense account used to track costs from purchases of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "incomeAccountId", "expenseAccountId" ], "additionalProperties": false }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" } }, "required": [ "name" ], "additionalProperties": false }, "TrackedServiceItemsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the service item object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive name of this service item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two service items could both have the `name` \"Web-Design\", but they could have unique `fullName` values, such as \"Consulting:Web-Design\" and \"Contracting:Web-Design\".\n\nMaximum length: 31 characters.", "example": "Web-Design", "type": "string", "maxLength": 31 }, "barcode": { "description": "The service item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this service item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The service item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent service item one level above this one in the hierarchy. For example, if this service item has a `fullName` of \"Consulting:Web-Design\", its parent has a `fullName` of \"Consulting\". If this service item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this service item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "forceUnitOfMeasureChange": { "description": "Indicates whether to allow changing the service item's unit-of-measure set (using the `unitOfMeasureSetId` field) when the base unit of the new unit-of-measure set does not match that of the currently assigned set. Without setting this field to `true` in this scenario, the request will fail with an error; hence, this field is equivalent to accepting the warning prompt in the QuickBooks UI.\n\nNOTE: Changing the base unit requires you to update the item's quantities-on-hand and cost to reflect the new unit; otherwise, these values will be inaccurate. Alternatively, consider creating a new item with the desired unit-of-measure set and deactivating the old item.", "example": false, "type": "boolean" }, "salesTaxCodeId": { "description": "The default sales-tax code for this service item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesOrPurchaseDetails": { "description": "Details for service items that are exclusively sold or exclusively purchased, but not both. This typically applies to non-inventory items (like a purchased office supply that isn't resold) or service items (like consulting services that are sold but not purchased).\n\n**IMPORTANT**: You cannot specify both `salesOrPurchaseDetails` and `salesAndPurchaseDetails` when modifying a service item because an item cannot have both configurations.", "type": "object", "properties": { "description": { "description": "A description of this item.", "example": "Hourly Consulting Service", "type": "string" }, "price": { "description": "The price at which this item is purchased or sold, represented as a decimal string.", "example": "19.99", "type": "string" }, "pricePercentage": { "description": "The price of this item expressed as a percentage, used instead of `price` when the item's cost is calculated as a percentage of another amount. For example, a service item that costs a percentage of another item's price.", "example": "10.5", "type": "string" }, "postingAccountId": { "description": "The posting account to which transactions involving this item are posted. This could be an income account when selling or an expense account when purchasing.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsAccount": { "description": "When `true`, applies the new account (specified by the `accountId` field) to all existing transactions associated with this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" } }, "additionalProperties": false }, "salesAndPurchaseDetails": { "description": "Details for service items that are both purchased and sold, such as reimbursable expenses or inventory items that are bought from vendors and sold to customers.\n\n**IMPORTANT**: You cannot specify both `salesAndPurchaseDetails` and `salesOrPurchaseDetails` when modifying a service item because an item cannot have both configurations.", "type": "object", "properties": { "salesDescription": { "description": "The description of this item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "expenseAccountId": { "description": "The expense account used to track costs from purchases of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsIncomeAccount": { "description": "When `true`, applies the new income account (specified by the `incomeAccountId` field) to all existing transactions that use this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" }, "updateExistingTransactionsExpenseAccount": { "description": "When `true`, applies the new expense account (specified by the `expenseAccountId` field) to all existing transactions that use this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" } }, "additionalProperties": false } }, "required": [], "additionalProperties": false }, "TrackedInventoryItemsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this inventory item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two inventory items could both have the `name` \"Cabinet\", but they could have unique `fullName` values, such as \"Kitchen:Cabinet\" and \"Inventory:Cabinet\".\n\nMaximum length: 31 characters.", "example": "Cabinet" }, "barcode": { "description": "The inventory item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this inventory item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "classId": { "description": "The inventory item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent inventory item one level above this one in the hierarchy. For example, if this inventory item has a `fullName` of \"Kitchen:Cabinet\", its parent has a `fullName` of \"Kitchen\". If this inventory item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "sku": { "description": "The inventory item's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this inventory item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The default sales-tax code for this inventory item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesDescription": { "description": "The description of this inventory item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this inventory item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this inventory item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this inventory item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this inventory item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this inventory item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "cogsAccountId": { "description": "The Cost of Goods Sold (COGS) account for this inventory item, tracking the original direct costs of producing goods sold.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this inventory item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "assetAccountId": { "description": "The asset account used to track the current value of this inventory item in inventory.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "reorderPoint": { "description": "The minimum quantity of this inventory item at which QuickBooks prompts for reordering.", "example": 50, "type": "number" }, "maximumQuantityOnHand": { "description": "The maximum quantity of this inventory item desired in inventory.", "example": 200, "type": "number" }, "quantityOnHand": { "description": "The number of units of this inventory item currently in inventory. `quantityOnHand` multiplied by `averageCost` equals `totalValue` for inventory item lists. To change the `quantityOnHand` for an inventory item, you must use an inventory-adjustment instead of updating the inventory item directly.", "example": 150, "type": "number" }, "totalValue": { "description": "The total value of this inventory item, represented as a decimal string. If `totalValue` is provided, `quantityOnHand` must also be provided and must be greater than zero. If both `quantityOnHand` and `purchaseCost` are provided, then `totalValue` will be set to `quantityOnHand` times `purchaseCost`, regardless of what `totalValue` is explicitly set to.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1500.00", "type": "string" }, "inventoryDate": { "description": "The date when this inventory item was converted into an inventory item from some other type of item, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" } }, "required": [ "name", "incomeAccountId", "cogsAccountId", "assetAccountId" ], "additionalProperties": false }, "TrackedInventoryItemsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the inventory item object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive name of this inventory item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two inventory items could both have the `name` \"Cabinet\", but they could have unique `fullName` values, such as \"Kitchen:Cabinet\" and \"Inventory:Cabinet\".\n\nMaximum length: 31 characters.", "example": "Cabinet", "type": "string", "maxLength": 31 }, "barcode": { "description": "The inventory item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this inventory item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The inventory item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent inventory item one level above this one in the hierarchy. For example, if this inventory item has a `fullName` of \"Kitchen:Cabinet\", its parent has a `fullName` of \"Kitchen\". If this inventory item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "sku": { "description": "The inventory item's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this inventory item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "forceUnitOfMeasureChange": { "description": "Indicates whether to allow changing the inventory item's unit-of-measure set (using the `unitOfMeasureSetId` field) when the base unit of the new unit-of-measure set does not match that of the currently assigned set. Without setting this field to `true` in this scenario, the request will fail with an error; hence, this field is equivalent to accepting the warning prompt in the QuickBooks UI.\n\nNOTE: Changing the base unit requires you to update the item's quantities-on-hand and cost to reflect the new unit; otherwise, these values will be inaccurate. Alternatively, consider creating a new item with the desired unit-of-measure set and deactivating the old item.", "example": false, "type": "boolean" }, "salesTaxCodeId": { "description": "The default sales-tax code for this inventory item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesDescription": { "description": "The description of this inventory item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this inventory item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this inventory item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsIncomeAccount": { "description": "When `true`, applies the new income account (specified by the `incomeAccountId` field) to all existing transactions that use this inventory item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" }, "purchaseDescription": { "description": "The description of this inventory item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this inventory item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this inventory item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "cogsAccountId": { "description": "The Cost of Goods Sold (COGS) account for this inventory item, tracking the original direct costs of producing goods sold.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsCogsAccount": { "description": "When `true`, applies the new COGS account (specified by the `cogsAccountId` field) to all existing transactions that use this inventory item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" }, "preferredVendorId": { "description": "The preferred vendor from whom this inventory item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "assetAccountId": { "description": "The asset account used to track the current value of this inventory item in inventory.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "reorderPoint": { "description": "The minimum quantity of this inventory item at which QuickBooks prompts for reordering.", "example": 50, "type": "number" }, "maximumQuantityOnHand": { "description": "The maximum quantity of this inventory item desired in inventory.", "example": 200, "type": "number" } }, "required": [], "additionalProperties": false }, "TrackedNonInventoryItemsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this non-inventory item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two non-inventory items could both have the `name` \"Printer Ink Cartridge\", but they could have unique `fullName` values, such as \"Office Supplies:Printer Ink Cartridge\" and \"Miscellaneous:Printer Ink Cartridge\".\n\nMaximum length: 31 characters.", "example": "Printer Ink Cartridge" }, "barcode": { "description": "The non-inventory item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this non-inventory item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "parentId": { "description": "The parent non-inventory item one level above this one in the hierarchy. For example, if this non-inventory item has a `fullName` of \"Office Supplies:Printer Ink Cartridge\", its parent has a `fullName` of \"Office Supplies\". If this non-inventory item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "classId": { "description": "The non-inventory item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "sku": { "description": "The non-inventory item's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this non-inventory item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The default sales-tax code for this non-inventory item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesOrPurchaseDetails": { "description": "Details for non-inventory items that are exclusively sold or exclusively purchased, but not both. This typically applies to non-inventory items (like a purchased office supply that isn't resold) or service items (like consulting services that are sold but not purchased).\n\n**IMPORTANT**: You must specify either `salesOrPurchaseDetails` or `salesAndPurchaseDetails` when creating a non-inventory item, but never both because an item cannot have both configurations.", "type": "object", "properties": { "description": { "description": "A description of this item.", "example": "Hourly Consulting Service", "type": "string" }, "price": { "description": "The price at which this item is purchased or sold, represented as a decimal string.", "example": "19.99", "type": "string" }, "pricePercentage": { "description": "The price of this item expressed as a percentage, used instead of `price` when the item's cost is calculated as a percentage of another amount. For example, a service item that costs a percentage of another item's price.", "example": "10.5", "type": "string" }, "postingAccountId": { "description": "The posting account to which transactions involving this item are posted. This could be an income account when selling or an expense account when purchasing.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "postingAccountId" ], "additionalProperties": false }, "salesAndPurchaseDetails": { "description": "Details for non-inventory items that are both purchased and sold, such as reimbursable expenses or inventory items that are bought from vendors and sold to customers.\n\n**IMPORTANT**: You must specify either `salesAndPurchaseDetails` or `salesOrPurchaseDetails` when creating a non-inventory item, but never both because an item cannot have both configurations.", "type": "object", "properties": { "salesDescription": { "description": "The description of this item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "expenseAccountId": { "description": "The expense account used to track costs from purchases of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "incomeAccountId", "expenseAccountId" ], "additionalProperties": false }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" } }, "required": [ "name" ], "additionalProperties": false }, "TrackedNonInventoryItemsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the non-inventory item object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive name of this non-inventory item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two non-inventory items could both have the `name` \"Printer Ink Cartridge\", but they could have unique `fullName` values, such as \"Office Supplies:Printer Ink Cartridge\" and \"Miscellaneous:Printer Ink Cartridge\".\n\nMaximum length: 31 characters.", "example": "Printer Ink Cartridge", "type": "string", "maxLength": 31 }, "barcode": { "description": "The non-inventory item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this non-inventory item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The non-inventory item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent non-inventory item one level above this one in the hierarchy. For example, if this non-inventory item has a `fullName` of \"Office Supplies:Printer Ink Cartridge\", its parent has a `fullName` of \"Office Supplies\". If this non-inventory item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "sku": { "description": "The non-inventory item's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this non-inventory item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "forceUnitOfMeasureChange": { "description": "Indicates whether to allow changing the non-inventory item's unit-of-measure set (using the `unitOfMeasureSetId` field) when the base unit of the new unit-of-measure set does not match that of the currently assigned set. Without setting this field to `true` in this scenario, the request will fail with an error; hence, this field is equivalent to accepting the warning prompt in the QuickBooks UI.\n\nNOTE: Changing the base unit requires you to update the item's quantities-on-hand and cost to reflect the new unit; otherwise, these values will be inaccurate. Alternatively, consider creating a new item with the desired unit-of-measure set and deactivating the old item.", "example": false, "type": "boolean" }, "salesTaxCodeId": { "description": "The default sales-tax code for this non-inventory item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesOrPurchaseDetails": { "description": "Details for non-inventory items that are exclusively sold or exclusively purchased, but not both. This typically applies to non-inventory items (like a purchased office supply that isn't resold) or service items (like consulting services that are sold but not purchased).\n\n**IMPORTANT**: You cannot specify both `salesOrPurchaseDetails` and `salesAndPurchaseDetails` when modifying a non-inventory item because an item cannot have both configurations.", "type": "object", "properties": { "description": { "description": "A description of this item.", "example": "Hourly Consulting Service", "type": "string" }, "price": { "description": "The price at which this item is purchased or sold, represented as a decimal string.", "example": "19.99", "type": "string" }, "pricePercentage": { "description": "The price of this item expressed as a percentage, used instead of `price` when the item's cost is calculated as a percentage of another amount. For example, a service item that costs a percentage of another item's price.", "example": "10.5", "type": "string" }, "postingAccountId": { "description": "The posting account to which transactions involving this item are posted. This could be an income account when selling or an expense account when purchasing.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsAccount": { "description": "When `true`, applies the new account (specified by the `accountId` field) to all existing transactions associated with this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" } }, "additionalProperties": false }, "salesAndPurchaseDetails": { "description": "Details for non-inventory items that are both purchased and sold, such as reimbursable expenses or inventory items that are bought from vendors and sold to customers.\n\n**IMPORTANT**: You cannot specify both `salesAndPurchaseDetails` and `salesOrPurchaseDetails` when modifying a non-inventory item because an item cannot have both configurations.", "type": "object", "properties": { "salesDescription": { "description": "The description of this item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "expenseAccountId": { "description": "The expense account used to track costs from purchases of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsIncomeAccount": { "description": "When `true`, applies the new income account (specified by the `incomeAccountId` field) to all existing transactions that use this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" }, "updateExistingTransactionsExpenseAccount": { "description": "When `true`, applies the new expense account (specified by the `expenseAccountId` field) to all existing transactions that use this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" } }, "additionalProperties": false } }, "required": [], "additionalProperties": false }, "TrackedInventoryAssemblyItemsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this inventory assembly item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two inventory assembly items could both have the `name` \"Deluxe Kit\", but they could have unique `fullName` values, such as \"Assemblies:Deluxe Kit\" and \"Inventory:Deluxe Kit\".\n\nMaximum length: 31 characters.", "example": "Deluxe Kit" }, "barcode": { "description": "The inventory assembly item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this inventory assembly item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "classId": { "description": "The inventory assembly item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent inventory assembly item one level above this one in the hierarchy. For example, if this inventory assembly item has a `fullName` of \"Assemblies:Deluxe Kit\", its parent has a `fullName` of \"Assemblies\". If this inventory assembly item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this inventory assembly item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The default sales-tax code for this inventory assembly item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesDescription": { "description": "The description of this inventory assembly item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this inventory assembly item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this inventory assembly item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this inventory assembly item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this inventory assembly item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this inventory assembly item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "cogsAccountId": { "description": "The Cost of Goods Sold (COGS) account for this inventory assembly item, tracking the original direct costs of producing goods sold.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this inventory assembly item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "assetAccountId": { "description": "The asset account used to track the current value of this inventory assembly item in inventory.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "buildNotificationThreshold": { "description": "The inventory assembly item's minimum quantity threshold that triggers a build notification in QuickBooks. When the sum of `quantityOnHand` (current inventory) and `quantityOnOrder` (pending purchase orders) drops below this threshold, QuickBooks will notify users that more units need to be built or assembled. This helps ensure adequate inventory levels for inventory assembly items.", "example": 10, "type": "number" }, "maximumQuantityOnHand": { "description": "The maximum quantity of this inventory assembly item desired in inventory.", "example": 200, "type": "number" }, "quantityOnHand": { "description": "The number of units of this inventory assembly item currently in inventory. `quantityOnHand` multiplied by `averageCost` equals `totalValue` for inventory item lists. To change the `quantityOnHand` for an inventory assembly item, you must use an inventory-adjustment instead of updating the inventory assembly item directly.", "example": 150, "type": "number" }, "totalValue": { "description": "The total value of this inventory assembly item, represented as a decimal string. If `totalValue` is provided, `quantityOnHand` must also be provided and must be greater than zero. If both `quantityOnHand` and `purchaseCost` are provided, then `totalValue` will be set to `quantityOnHand` times `purchaseCost`, regardless of what `totalValue` is explicitly set to.\n\nDecimal string format: exactly 2 decimal places when cents are included and up to 13 digits before the decimal point (for example, \"123.45\").", "example": "1500.00", "type": "string" }, "inventoryDate": { "description": "The date when this inventory assembly item was converted into an inventory item from some other type of item, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "lines": { "description": "The inventory assembly item's lines.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "inventoryItemId": { "description": "The inventory item associated with this inventory assembly item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "quantity": { "description": "The quantity of the item associated with this inventory assembly item line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" } }, "additionalProperties": false } } }, "required": [ "name", "incomeAccountId", "cogsAccountId", "assetAccountId" ], "additionalProperties": false }, "TrackedInventoryAssemblyItemsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the inventory assembly item object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive name of this inventory assembly item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two inventory assembly items could both have the `name` \"Deluxe Kit\", but they could have unique `fullName` values, such as \"Assemblies:Deluxe Kit\" and \"Inventory:Deluxe Kit\".\n\nMaximum length: 31 characters.", "example": "Deluxe Kit", "type": "string", "maxLength": 31 }, "barcode": { "description": "The inventory assembly item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this inventory assembly item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The inventory assembly item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent inventory assembly item one level above this one in the hierarchy. For example, if this inventory assembly item has a `fullName` of \"Assemblies:Deluxe Kit\", its parent has a `fullName` of \"Assemblies\". If this inventory assembly item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "sku": { "description": "The inventory assembly item's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this inventory assembly item, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "forceUnitOfMeasureChange": { "description": "Indicates whether to allow changing the inventory assembly item's unit-of-measure set (using the `unitOfMeasureSetId` field) when the base unit of the new unit-of-measure set does not match that of the currently assigned set. Without setting this field to `true` in this scenario, the request will fail with an error; hence, this field is equivalent to accepting the warning prompt in the QuickBooks UI.\n\nNOTE: Changing the base unit requires you to update the item's quantities-on-hand and cost to reflect the new unit; otherwise, these values will be inaccurate. Alternatively, consider creating a new item with the desired unit-of-measure set and deactivating the old item.", "example": false, "type": "boolean" }, "salesTaxCodeId": { "description": "The default sales-tax code for this inventory assembly item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesDescription": { "description": "The description of this inventory assembly item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this inventory assembly item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this inventory assembly item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsIncomeAccount": { "description": "When `true`, applies the new income account (specified by the `incomeAccountId` field) to all existing transactions that use this inventory assembly item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" }, "purchaseDescription": { "description": "The description of this inventory assembly item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this inventory assembly item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this inventory assembly item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "cogsAccountId": { "description": "The Cost of Goods Sold (COGS) account for this inventory assembly item, tracking the original direct costs of producing goods sold.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this inventory assembly item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "assetAccountId": { "description": "The asset account used to track the current value of this inventory assembly item in inventory.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "buildNotificationThreshold": { "description": "The inventory assembly item's minimum quantity threshold that triggers a build notification in QuickBooks. When the sum of `quantityOnHand` (current inventory) and `quantityOnOrder` (pending purchase orders) drops below this threshold, QuickBooks will notify users that more units need to be built or assembled. This helps ensure adequate inventory levels for inventory assembly items.", "example": 10, "type": "number" }, "maximumQuantityOnHand": { "description": "The maximum quantity of this inventory assembly item desired in inventory.", "example": 200, "type": "number" }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this inventory assembly item. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "lines": { "description": "The inventory assembly item's lines.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "inventoryItemId": { "description": "The inventory item associated with this inventory assembly item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "quantity": { "description": "The quantity of the item associated with this inventory assembly item line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item is a discount item.", "example": 5, "type": "number" } }, "additionalProperties": false } } }, "required": [], "additionalProperties": false }, "TrackedOtherChargeItemsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this other charge item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two other charge items could both have the `name` \"Overnight Delivery\", but they could have unique `fullName` values, such as \"Shipping Charges:Overnight Delivery\" and \"Misc Fees:Overnight Delivery\".\n\nMaximum length: 31 characters.", "example": "Overnight Delivery" }, "barcode": { "description": "The other charge item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this other charge item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "classId": { "description": "The other charge item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent other charge item one level above this one in the hierarchy. For example, if this other charge item has a `fullName` of \"Shipping Charges:Overnight Delivery\", its parent has a `fullName` of \"Shipping Charges\". If this other charge item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "salesTaxCodeId": { "description": "The default sales-tax code for this other charge item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesOrPurchaseDetails": { "description": "Details for other charge items that are exclusively sold or exclusively purchased, but not both. This typically applies to non-inventory items (like a purchased office supply that isn't resold) or service items (like consulting services that are sold but not purchased).\n\n**IMPORTANT**: You must specify either `salesOrPurchaseDetails` or `salesAndPurchaseDetails` when creating an other charge item, but never both because an item cannot have both configurations.", "type": "object", "properties": { "description": { "description": "A description of this item.", "example": "Hourly Consulting Service", "type": "string" }, "price": { "description": "The price at which this item is purchased or sold, represented as a decimal string.", "example": "19.99", "type": "string" }, "pricePercentage": { "description": "The price of this item expressed as a percentage, used instead of `price` when the item's cost is calculated as a percentage of another amount. For example, a service item that costs a percentage of another item's price.", "example": "10.5", "type": "string" }, "postingAccountId": { "description": "The posting account to which transactions involving this item are posted. This could be an income account when selling or an expense account when purchasing.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "postingAccountId" ], "additionalProperties": false }, "salesAndPurchaseDetails": { "description": "Details for other charge items that are both purchased and sold, such as reimbursable expenses or inventory items that are bought from vendors and sold to customers.\n\n**IMPORTANT**: You must specify either `salesAndPurchaseDetails` or `salesOrPurchaseDetails` when creating an other charge item, but never both because an item cannot have both configurations.", "type": "object", "properties": { "salesDescription": { "description": "The description of this item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "expenseAccountId": { "description": "The expense account used to track costs from purchases of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "incomeAccountId", "expenseAccountId" ], "additionalProperties": false }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" } }, "required": [ "name" ], "additionalProperties": false }, "TrackedOtherChargeItemsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the other charge item object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive name of this other charge item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two other charge items could both have the `name` \"Overnight Delivery\", but they could have unique `fullName` values, such as \"Shipping Charges:Overnight Delivery\" and \"Misc Fees:Overnight Delivery\".\n\nMaximum length: 31 characters.", "example": "Overnight Delivery", "type": "string", "maxLength": 31 }, "barcode": { "description": "The other charge item's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this other charge item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The other charge item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "parentId": { "description": "The parent other charge item one level above this one in the hierarchy. For example, if this other charge item has a `fullName` of \"Shipping Charges:Overnight Delivery\", its parent has a `fullName` of \"Shipping Charges\". If this other charge item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "salesTaxCodeId": { "description": "The default sales-tax code for this other charge item, determining whether it is taxable or non-taxable. This can be overridden at the transaction-line level.\n\nDefault codes include \"Non\" (non-taxable) and \"Tax\" (taxable), but custom codes can also be created in QuickBooks Desktop. If QuickBooks Desktop is not set up to charge sales tax (via the \"Do You Charge Sales Tax?\" preference), it assigns the default non-taxable sales-tax code configured in the company file to all sales.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesOrPurchaseDetails": { "description": "Details for other charge items that are exclusively sold or exclusively purchased, but not both. This typically applies to non-inventory items (like a purchased office supply that isn't resold) or service items (like consulting services that are sold but not purchased).\n\n**IMPORTANT**: You cannot specify both `salesOrPurchaseDetails` and `salesAndPurchaseDetails` when modifying an other charge item because an item cannot have both configurations.", "type": "object", "properties": { "description": { "description": "A description of this item.", "example": "Hourly Consulting Service", "type": "string" }, "price": { "description": "The price at which this item is purchased or sold, represented as a decimal string.", "example": "19.99", "type": "string" }, "pricePercentage": { "description": "The price of this item expressed as a percentage, used instead of `price` when the item's cost is calculated as a percentage of another amount. For example, a service item that costs a percentage of another item's price.", "example": "10.5", "type": "string" }, "postingAccountId": { "description": "The posting account to which transactions involving this item are posted. This could be an income account when selling or an expense account when purchasing.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsAccount": { "description": "When `true`, applies the new account (specified by the `accountId` field) to all existing transactions associated with this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" } }, "additionalProperties": false }, "salesAndPurchaseDetails": { "description": "Details for other charge items that are both purchased and sold, such as reimbursable expenses or inventory items that are bought from vendors and sold to customers.\n\n**IMPORTANT**: You cannot specify both `salesAndPurchaseDetails` and `salesOrPurchaseDetails` when modifying an other charge item because an item cannot have both configurations.", "type": "object", "properties": { "salesDescription": { "description": "The description of this item that appears on sales forms (e.g., invoices, sales receipts) when sold to customers.", "example": "High-quality steel bolts suitable for construction", "type": "string" }, "salesPrice": { "description": "The price at which this item is sold to customers, represented as a decimal string.", "example": "19.99", "type": "string" }, "incomeAccountId": { "description": "The income account used to track revenue from sales of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "purchaseDescription": { "description": "The description of this item that appears on purchase forms (e.g., checks, bills, item receipts) when it is ordered or bought from vendors.", "example": "Bulk purchase of steel bolts for inventory", "type": "string" }, "purchaseCost": { "description": "The cost at which this item is purchased from vendors, represented as a decimal string.", "example": "15.75", "type": "string" }, "purchaseTaxCodeId": { "description": "The tax code applied to purchases of this item. Applicable in regions where purchase taxes are used, such as Canada or the UK.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "expenseAccountId": { "description": "The expense account used to track costs from purchases of this item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "preferredVendorId": { "description": "The preferred vendor from whom this item is typically purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "updateExistingTransactionsIncomeAccount": { "description": "When `true`, applies the new income account (specified by the `incomeAccountId` field) to all existing transactions that use this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" }, "updateExistingTransactionsExpenseAccount": { "description": "When `true`, applies the new expense account (specified by the `expenseAccountId` field) to all existing transactions that use this item. This updates historical data and should be used with caution. The update will fail if any affected transaction falls within a closed accounting period. If this parameter is not specified, QuickBooks will prompt the user before making any changes.", "example": false, "type": "boolean" } }, "additionalProperties": false } }, "required": [], "additionalProperties": false }, "TrackedItemGroupsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this item group, unique across all item groups.\n\n**NOTE**: Item groups do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.\n\nMaximum length: 31 characters.", "example": "Office Supplies Bundle" }, "barcode": { "description": "The item group's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this item group is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "description": { "description": "The item group's description that will appear on sales forms that include this item.", "example": "Complete office starter kit with essential supplies for new employees.", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this item group, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shouldPrintItemsInGroup": { "type": "boolean", "description": "Indicates whether the individual items in this item group and their separate amounts appear on printed forms.", "example": true }, "externalId": { "type": "string", "format": "uuid", "description": "A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.\n\n**IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.", "example": "12345678-abcd-1234-abcd-1234567890ab" }, "lines": { "description": "The item lines in this item group.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item group line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this item group line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item group line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" } }, "additionalProperties": false } } }, "required": [ "name", "shouldPrintItemsInGroup" ], "additionalProperties": false }, "TrackedItemGroupsUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the item group object you are updating, which you can get by fetching the object first. Provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.", "example": "1721172183" }, "name": { "description": "The case-insensitive unique name of this item group, unique across all item groups.\n\n**NOTE**: Item groups do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.\n\nMaximum length: 31 characters.", "example": "Office Supplies Bundle", "type": "string", "maxLength": 31 }, "barcode": { "description": "The item group's barcode.", "type": "object", "properties": { "value": { "description": "The item's barcode value.", "example": "012345678905", "type": "string" }, "assignEvenIfUsed": { "description": "Indicates whether to assign the barcode even if it is already used.", "example": false, "default": false, "type": "boolean" }, "allowOverride": { "description": "Indicates whether to allow the barcode to be overridden.", "example": false, "default": false, "type": "boolean" } }, "additionalProperties": false }, "isActive": { "description": "Indicates whether this item group is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "description": { "description": "The item group's description that will appear on sales forms that include this item.", "example": "Complete office starter kit with essential supplies for new employees.", "type": "string" }, "unitOfMeasureSetId": { "description": "The unit-of-measure set associated with this item group, which consists of a base unit and related units.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "forceUnitOfMeasureChange": { "description": "Indicates whether to allow changing the item group's unit-of-measure set (using the `unitOfMeasureSetId` field) when the base unit of the new unit-of-measure set does not match that of the currently assigned set. Without setting this field to `true` in this scenario, the request will fail with an error; hence, this field is equivalent to accepting the warning prompt in the QuickBooks UI.\n\nNOTE: Changing the base unit requires you to update the item's quantities-on-hand and cost to reflect the new unit; otherwise, these values will be inaccurate. Alternatively, consider creating a new item with the desired unit-of-measure set and deactivating the old item.", "example": false, "type": "boolean" }, "shouldPrintItemsInGroup": { "description": "Indicates whether the individual items in this item group and their separate amounts appear on printed forms.", "example": true, "type": "boolean" }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this item group. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "lines": { "description": "The item lines in this item group.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item group line. This can refer to any good or service that the business buys or sells, including item types such as a service item, inventory item, or special calculation item like a discount item or sales-tax item.", "example": "80000001-1234567890", "type": "string", "maxLength": 512 }, "quantity": { "description": "The quantity of the item group associated with this item group line. This field cannot be cleared.\n\n**NOTE**: Do not use this field if the associated item group is a discount item group.", "example": 5, "type": "number" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item group line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" } }, "additionalProperties": false } } }, "required": [], "additionalProperties": false }, "TrackedContactCreate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Current owner customer/job revisionNumber, not the person's revision. Never substitute a newer revision automatically." }, "salutation": { "type": "string", "minLength": 1, "maxLength": 15 }, "firstName": { "type": "string", "minLength": 1, "maxLength": 25 }, "middleName": { "type": "string", "minLength": 1, "maxLength": 5 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 25 }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 41 }, "email": { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "description": "Person's own single email address; native MainEmail, not the owner's Email." }, "phone": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own work phone; native WorkPhone, not the owner's Phone." }, "mobile": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own mobile phone; native Mobile." } }, "required": [ "firstName" ], "additionalProperties": false }, "TrackedContactUpdate": { "type": "object", "properties": { "revisionNumber": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Current owner customer/job revisionNumber, not the person's revision. Never substitute a newer revision automatically." }, "salutation": { "type": "string", "minLength": 1, "maxLength": 15 }, "firstName": { "type": "string", "minLength": 1, "maxLength": 25 }, "middleName": { "type": "string", "minLength": 1, "maxLength": 5 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 25 }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 41 }, "email": { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "description": "Person's own single email address; native MainEmail, not the owner's Email." }, "phone": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own work phone; native WorkPhone, not the owner's Phone." }, "mobile": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Person's own mobile phone; native Mobile." }, "contactRevisionNumber": { "type": "string", "minLength": 1, "maxLength": 16, "description": "The person's current EditSequence: mirror contact revisionNumber or write receipt contacts[].revisionNumber. Distinct from the owner revision." } }, "required": [], "additionalProperties": false } }, "parameters": {} }, "paths": { "/api/management/v1/whoami": { "get": { "summary": "Read developer credential identity and permissions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectDeveloperPrincipalDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Read developer credential identity and permissions.", "x-required-permissions": [] } }, "/api/management/v1/account/branding": { "get": { "summary": "Read account branding", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "$ref": "#/components/schemas/BoostConnectAccountBrandingDto" } }, "required": [ "branding" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Reads account branding used by hosted setup, portal surfaces, and generated QWC files. Use it to show the correct customer-facing product name, support contact, accent color, and Web Connector app copy for the authenticated account.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Changes are account scoped and may affect hosted setup and future generated QWC files.", "x-required-permissions": [ "account:read" ] }, "patch": { "summary": "Update account branding", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBoostConnectAccountBrandingRequestDto" } } }, "description": "JSON request payload for this operation." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "$ref": "#/components/schemas/BoostConnectAccountBrandingDto" } }, "required": [ "branding" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates account branding used by hosted setup, portal surfaces, and generated QWC files. Changes affect newly rendered setup pages and newly downloaded QWC files; already imported Web Connector files keep the values they contained when downloaded.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Changes are account scoped and may affect hosted setup and future generated QWC files.", "x-required-permissions": [ "account:write" ] } }, "/api/management/v1/projects": { "get": { "summary": "List projects", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/BoostConnectProjectDto" } } }, "required": [ "projects" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists projects visible to the authenticated API key. Projects group connections, API keys, callback allowlists, branding overrides, and webhook endpoints.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.", "x-required-permissions": [ "projects:read" ] }, "post": { "summary": "Create project", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBoostConnectProjectRequestDto" } } }, "description": "Project settings to create or update." }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/BoostConnectProjectDto" } }, "required": [ "project" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a project for isolating QuickBooks Desktop connections and API keys. Use separate projects when customers, environments, or integration surfaces need independent callback URLs, branding, or webhook destinations.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.", "x-required-permissions": [ "projects:write" ] } }, "/api/management/v1/projects/{projectId}": { "get": { "summary": "Read project", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/BoostConnectProjectDto" } }, "required": [ "project" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Reads one project and its connection-facing configuration. Use this before creating connections or setup links when the integration needs project-specific branding or callback settings.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.", "x-required-permissions": [ "project:read", "projects:read" ] }, "patch": { "summary": "Update project", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBoostConnectProjectRequestDto" } } }, "description": "Project settings to create or update." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/BoostConnectProjectDto" } }, "required": [ "project" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates project name, tags, status, branding, or callback allowlist. Callback URL changes control where hosted setup sessions may redirect after customer setup.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.", "x-required-permissions": [ "projects:write" ] }, "delete": { "summary": "Archive project", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/BoostConnectProjectDto" } }, "required": [ "project" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Archives a project so new connections and API keys should no longer be created for it. Existing integrations should move traffic to an active project before archive.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.", "x-required-permissions": [ "projects:write" ] } }, "/api/management/v1/tokens": { "get": { "summary": "List API tokens", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/BoostConnectApiTokenDto" } } }, "required": [ "tokens" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists API tokens for the authenticated account or project. Token records expose metadata such as name, status, prefix, creation time, revocation time, and last use, but never return the full bearer secret.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.", "x-required-permissions": [ "credentials:read" ] }, "post": { "summary": "Create API token", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBoostConnectApiTokenRequestDto" } } }, "description": "API token access and tags." }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectApiTokenCreatedDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an API token and returns the full bearer token one time. Store the bearer token immediately because later reads only return token metadata and prefix.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- The full bearer token is returned only once and must be stored by the caller.", "x-required-permissions": [ "credentials:write" ] } }, "/api/management/v1/tokens/{tokenId}": { "get": { "summary": "Read API token", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The API token ID." }, "required": true, "name": "tokenId", "in": "path", "description": "The API token ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "$ref": "#/components/schemas/BoostConnectApiTokenDto" } }, "required": [ "token" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Reads API token metadata by token ID. Use it to confirm status, display name, prefix, and last-use information without exposing the bearer secret.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires an API token ID in the path.", "x-required-permissions": [ "credentials:read" ] }, "patch": { "summary": "Update API token access or tags", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The API token ID." }, "required": true, "name": "tokenId", "in": "path", "description": "The API token ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBoostConnectApiTokenRequestDto" } } }, "description": "API token access and tags." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "$ref": "#/components/schemas/BoostConnectApiTokenDto" } }, "required": [ "token" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Renames an API token without changing the bearer secret. Use this for operator-facing labels and rotation bookkeeping.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires an API token ID in the path.", "x-required-permissions": [ "credentials:write" ] }, "delete": { "summary": "Delete revoked API token", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The API token ID." }, "required": true, "name": "tokenId", "in": "path", "description": "The API token ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Deletes metadata for an already revoked API token. This is cleanup only and should not be used as the primary way to stop an active token.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires an API token ID in the path.", "x-required-permissions": [ "credentials:write" ] } }, "/api/management/v1/tokens/{tokenId}/regenerate": { "post": { "summary": "Regenerate API token", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The API token ID." }, "required": true, "name": "tokenId", "in": "path", "description": "The API token ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectApiTokenCreatedDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Regenerates an API token by revoking the old bearer secret and returning a replacement secret one time. Update clients before or immediately after regeneration because old credentials stop working.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires an API token ID in the path.\n- The full bearer token is returned only once and must be stored by the caller.", "x-required-permissions": [ "credentials:write" ] } }, "/api/management/v1/tokens/{tokenId}/revoke": { "post": { "summary": "Revoke API token", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The API token ID." }, "required": true, "name": "tokenId", "in": "path", "description": "The API token ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "$ref": "#/components/schemas/BoostConnectApiTokenDto" } }, "required": [ "token" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Revokes an API token so clients using its bearer secret can no longer call protected APIs. Use this when a token is compromised, obsolete, or no longer assigned to an active integration.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires an API token ID in the path.", "x-required-permissions": [ "credentials:write" ] } }, "/api/management/v1/projects/{projectId}/webhook-endpoint": { "get": { "summary": "Read project webhook endpoint", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "allOf": [ { "$ref": "#/components/schemas/BoostConnectWebhookEndpointDto" }, { "nullable": true } ] } }, "required": [ "webhook" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Reads the current webhook endpoint for the specified project. Use this when an integration supports one primary event destination.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:read" ] }, "post": { "summary": "Create project webhook endpoint", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBoostConnectWebhookEndpointRequestDto" } } }, "description": "Webhook endpoint settings, including delivery URL, subscribed event types, subscribed resources, and status." }, "responses": { "200": { "description": "An exact create replay returned the existing webhook endpoint and signing secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointCreatedDto" } } } }, "201": { "description": "Webhook endpoint created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointCreatedDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The webhook URL or configuration conflicts with an existing endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The project webhook endpoint or serialized target capacity was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a webhook endpoint for the specified project. By default one project-level endpoint receives signed events for every connection; optionally set connectionScope to selected with connectionIds for isolated per-connection delivery.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:write" ] }, "patch": { "summary": "Update project webhook endpoint", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBoostConnectWebhookEndpointRequestDto" } } }, "description": "Webhook endpoint settings, including delivery URL, subscribed event types, subscribed resources, and status." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointDto" } }, "required": [ "webhook" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The webhook URL or configuration conflicts with an existing endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The project webhook endpoint or serialized target capacity was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a webhook endpoint for the specified project. Use this to rotate URL, subscribed event types, subscribed resources, optional connection filter, or delivery status.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:write" ] } }, "/api/management/v1/projects/{projectId}/webhook-endpoints": { "get": { "summary": "List project webhook endpoints", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointListDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists webhook endpoints for the specified project. Use this to inspect all delivery targets that receive signed Boost Connect QBD events.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:read" ] }, "post": { "summary": "Create project webhook endpoint", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBoostConnectWebhookEndpointRequestDto" } } }, "description": "Webhook endpoint settings, including delivery URL, subscribed event types, subscribed resources, and status." }, "responses": { "200": { "description": "An exact create replay returned the existing webhook endpoint and signing secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointCreatedDto" } } } }, "201": { "description": "Webhook endpoint created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointCreatedDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The webhook URL or configuration conflicts with an existing endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The project webhook endpoint or serialized target capacity was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a webhook endpoint for the specified project. By default one project-level endpoint receives signed events for every connection; optionally set connectionScope to selected with connectionIds for isolated per-connection delivery.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:write" ] } }, "/api/management/v1/projects/{projectId}/webhook-endpoints/{webhookId}": { "get": { "summary": "Read project webhook endpoint by id", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." }, { "schema": { "type": "string", "minLength": 1, "description": "The webhook endpoint ID." }, "required": true, "name": "webhookId", "in": "path", "description": "The webhook endpoint ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointDto" } }, "required": [ "webhook" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Reads one webhook endpoint for the specified project by webhook ID, including subscribed events, resources, connection filter, status, and signing metadata.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:read" ] }, "patch": { "summary": "Update project webhook endpoint by id", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." }, { "schema": { "type": "string", "minLength": 1, "description": "The webhook endpoint ID." }, "required": true, "name": "webhookId", "in": "path", "description": "The webhook endpoint ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBoostConnectWebhookEndpointRequestDto" } } }, "description": "Webhook endpoint settings, including delivery URL, subscribed event types, subscribed resources, and status." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/BoostConnectWebhookEndpointDto" } }, "required": [ "webhook" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The webhook URL or configuration conflicts with an existing endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The project webhook endpoint or serialized target capacity was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a webhook endpoint for the specified project. Use this to rotate URL, subscribed event types, subscribed resources, optional connection filter, or delivery status.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:write" ] }, "delete": { "summary": "Delete project webhook endpoint", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect project ID." }, "required": true, "name": "projectId", "in": "path", "description": "The Boost Connect project ID." }, { "schema": { "type": "string", "minLength": 1, "description": "The webhook endpoint ID." }, "required": true, "name": "webhookId", "in": "path", "description": "The webhook endpoint ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBoostConnectWebhookEndpointResponseDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Webhook endpoint storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Deletes a webhook endpoint for the specified project. Events stop delivering to this destination after deletion.\n\n**Requirements:**\n- Requires bearer authentication for the owning account.\n- Requires a project ID in the path.\n- Webhook endpoint URLs must be reachable over HTTPS and able to verify Boost event signatures.", "x-required-permissions": [ "webhooks:write" ] } } } }