{ "openapi": "3.0.3", "info": { "title": "Boost Connect QBD API", "version": "0.1.0", "description": "Standalone QuickBooks Desktop/QWC connection 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/qbd/v1/connections": { "get": { "summary": "List QuickBooks Desktop connections", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Filters connections by the customer identifier from the caller's system." }, "required": false, "name": "externalCustomerId", "in": "query", "description": "Filters connections by the customer identifier from the caller's system." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters connections by the connection identifier from the caller's system." }, "required": false, "name": "externalConnectionId", "in": "query", "description": "Filters connections by the connection identifier from the caller's system." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/QbdPublicConnectionDto" } } }, "required": [ "connections" ] } } } }, "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 QuickBooks Desktop connections for the authenticated account or project. Use optional external customer or connection identifiers to find the Boost connection that maps to your own system.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.", "x-required-permissions": [ "connections:read" ] }, "post": { "summary": "Create QuickBooks Desktop connection", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQbdConnectionRequestDto" } } }, "description": "Connection creation settings, including optional external identifiers and metadata used to map this Boost connection to the caller's system." }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdConnectionCreatedDto" } } } }, "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": "Idempotency conflict, provisioning pending, or setup session required. Preserve connectionId and do not invent a new idempotency key to recover.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "connectionId" ], "properties": { "error": { "type": "string", "enum": [ "qbd_idempotency_conflict", "connection_provisioning_pending", "connection_setup_required" ] }, "connectionId": { "type": "string" } } } } } } }, "description": "Creates a Boost Connect QBD connection and returns the first Web Connector setup materials. The response includes the hosted setup URL, QWC download URL, and one-time Web Connector password needed to connect a QuickBooks Desktop company file.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n\nAPI-only onboarding returns the connection, QBWC password and setup/download links. Reuse the same body idempotencyKey and identical payload for retries. The key is scoped to account and project. Exact retries reuse an active setup secret, never silently rotate it. A changed payload returns qbd_idempotency_conflict (409). Concurrent/incomplete setup may return connection_provisioning_pending (409, retry the same request). Expired/missing setup material returns connection_setup_required (409) with connectionId; explicitly create a new setup session, which rotates the QBWC password. No per-Monday-tenant connector API key is required.", "x-required-permissions": [ "connections:write" ] } }, "/api/qbd/v1/connections/{id}": { "get": { "summary": "Read QuickBooks Desktop connection", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" } }, "required": [ "connection" ] } } } }, "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 QuickBooks Desktop connection, including status, queue depth, Web Connector username, and last-seen timestamps. Use it before live API calls to verify the connection exists and belongs to the expected project.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:read" ] }, "patch": { "summary": "Update QuickBooks Desktop connection", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQbdConnectionRequestDto" } } }, "description": "JSON request payload for this operation." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" } }, "required": [ "connection" ] } } } }, "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 mutable connection settings such as display name or connection status. Disabling a connection stops new live API work even if Web Connector still checks in.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:write" ] }, "delete": { "summary": "Disable QuickBooks Desktop connection", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbdPublicConnectionDto" } }, "required": [ "connection" ] } } } }, "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": "Disables a QuickBooks Desktop connection. Use this when an integration should stop sending work to a company file without deleting historical connection metadata.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:write" ] } }, "/api/qbd/v1/connections/{id}/mirror": { "get": { "summary": "Read mirror policy, per-resource readiness and connector capabilities", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "mirror": { "allOf": [ { "$ref": "#/components/schemas/QbdMirrorConfigurationDto" }, { "nullable": true } ] }, "resources": { "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" ] }, "searchDomain": { "type": "string", "nullable": true, "enum": [ "contacts", "products", null ] }, "sync": { "allOf": [ { "$ref": "#/components/schemas/QbdMirrorSyncStateDto" }, { "nullable": true } ] }, "ready": { "type": "boolean" } }, "required": [ "resourceType", "searchDomain", "sync", "ready" ] } }, "capabilities": { "type": "object", "properties": { "fieldPolicyVersion": { "type": "string", "enum": [ "qbd-native-current-v2" ] }, "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" ] } }, "readModes": { "type": "array", "items": { "type": "string", "enum": [ "mirror", "mirror_then_refresh" ] } }, "searchDomains": { "type": "array", "items": { "type": "string", "enum": [ "contacts", "products" ] } }, "recordModel": { "type": "string", "enum": [ "current_state" ] }, "nativeWriteResultRetentionDays": { "type": "number", "enum": [ 30 ] } }, "required": [ "fieldPolicyVersion", "resourceTypes", "readModes", "searchDomains", "recordModel", "nativeWriteResultRetentionDays" ] } }, "required": [ "mirror", "resources", "capabilities" ] } } } }, "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 mirror policy, per-resource readiness and connector capabilities.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:read" ] }, "put": { "summary": "Replace connection mirror policy using an expected revision (connections:write)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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 }, "expectedRevision": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true } }, "required": [ "policy", "expectedRevision" ], "additionalProperties": false } } }, "description": "JSON request payload for this operation." }, "responses": { "200": { "description": "Existing policy replaced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mirror": { "$ref": "#/components/schemas/QbdMirrorConfigurationDto" } }, "required": [ "mirror" ] } } } }, "201": { "description": "First connection mirror policy created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mirror": { "$ref": "#/components/schemas/QbdMirrorConfigurationDto" } }, "required": [ "mirror" ] } } } }, "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": "Replace connection mirror policy using an expected revision (connections:write).\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:write" ] } }, "/api/qbd/v1/connections/{id}/mirror/refresh": { "post": { "summary": "Refresh all enabled mirror resources now, bypassing scheduled freshness delays (connections:write)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enqueuedOperationCount": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "queued", "syncing", "waiting_for_connection", "waiting_for_queue", "complete" ] }, "requestedAt": { "type": "string", "nullable": true }, "pendingResourceCount": { "type": "integer", "minimum": 0 }, "runningResourceCount": { "type": "integer", "minimum": 0 }, "completedResourceCount": { "type": "integer", "minimum": 0 }, "failedResourceCount": { "type": "integer", "minimum": 0 } }, "required": [ "enqueuedOperationCount", "status", "requestedAt", "pendingResourceCount", "runningResourceCount", "completedResourceCount", "failedResourceCount" ] } } } }, "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": "Refresh all enabled mirror resources now, bypassing scheduled freshness delays (connections:write).\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:write" ] } }, "/api/qbd/v1/connections/{id}/health-check": { "get": { "summary": "Check whether a QuickBooks Desktop connection is ready for live API calls", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdConnectionHealthCheckDto" } } } }, "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": "Checks whether a QuickBooks Desktop connection can process live work. It reports queue state, active operation state, recent Web Connector activity, and whether the connection is ready for API reads or writes.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- QuickBooks Web Connector must be able to check in for live QuickBooks Desktop reads or writes to complete.", "x-required-permissions": [ "diagnostics:read" ] } }, "/api/qbd/v1/health-check": { "get": { "summary": "Check whether a QuickBooks Desktop connection is ready for live API calls", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdConnectionHealthCheckDto" } } } }, "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": "Checks whether the specified QuickBooks Desktop connection is active and can process requests end-to-end. This is useful for showing a \"connection status\" indicator in your app. If an error occurs, the standard API error response will be returned. As with any request to QuickBooks Desktop, the health check may fail if the application is not running, the wrong company file is open, or if a modal dialog is open. Timeout is 60 seconds.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "diagnostics:read" ] } }, "/api/qbd/v1/customers": { "get": { "summary": "List QuickBooks Desktop customers and jobs", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 150, "default": 150, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return. Mirror mode: default/max 100. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response. Mirror mode: {\"type\":\"string\",\"maxLength\":12000}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "default": "active", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop. Mirror mode: {\"type\":\"string\",\"format\":\"date-time\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs whose QuickBooks Desktop name contains this text." }, "required": false, "name": "nameContains", "in": "query", "description": "Filters customers or jobs whose QuickBooks Desktop name contains this text." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs whose QuickBooks Desktop name starts with this text." }, "required": false, "name": "nameStartsWith", "in": "query", "description": "Filters customers or jobs whose QuickBooks Desktop name starts with this text." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs whose QuickBooks Desktop name ends with this text." }, "required": false, "name": "nameEndsWith", "in": "query", "description": "Filters customers or jobs whose QuickBooks Desktop name ends with this text." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs by exact total balance." }, "required": false, "name": "totalBalance", "in": "query", "description": "Filters customers or jobs by exact total balance." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance greater than this amount." }, "required": false, "name": "totalBalanceGreaterThan", "in": "query", "description": "Filters customers or jobs with total balance greater than this amount." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance greater than or equal to this amount." }, "required": false, "name": "totalBalanceGreaterThanOrEqualTo", "in": "query", "description": "Filters customers or jobs with total balance greater than or equal to this amount." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance less than this amount." }, "required": false, "name": "totalBalanceLessThan", "in": "query", "description": "Filters customers or jobs with total balance less than this amount." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance less than or equal to this amount." }, "required": false, "name": "totalBalanceLessThanOrEqualTo", "in": "query", "description": "Filters customers or jobs with total balance less than or equal to this amount." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "boolean", "default": false, "description": "When true, omits alternate shipping addresses from customer responses to reduce QuickBooks Desktop read time." }, "required": false, "name": "excludeAlternateShippingAddresses", "in": "query", "description": "When true, omits alternate shipping addresses from customer responses to reduce QuickBooks Desktop read time." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "name" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "customer", "job" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "parentId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "jobStatus", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "none", "pending", "awarded", "in_progress", "closed", "not_awarded" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorList" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of customers. Use the `cursor` parameter to paginate through the results.\n\n**IMPORTANT**: If this request times out or is slow, set `excludeAlternateShippingAddresses=true` to significantly improve performance. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "kind", "parentId", "active", "jobStatus", "email" ] }, "post": { "summary": "Create QuickBooks Desktop customers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedCustomersCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new customer.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/customers/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop customer or job", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "boolean", "default": false, "description": "When true, omits alternate shipping addresses from customer responses to reduce QuickBooks Desktop read time." }, "required": false, "name": "excludeAlternateShippingAddresses", "in": "query", "description": "When true, omits alternate shipping addresses from customer responses to reduce QuickBooks Desktop read time." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerResourceDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorDetail" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a customer by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific customers by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId" ] }, "post": { "summary": "Update QuickBooks Desktop customers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the customer to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the customer to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedCustomersUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing customer.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/customers/{id}/contacts": { "post": { "summary": "Add an additional contact to an existing QuickBooks customer or job", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Native parent customer or job ListID, not a contact ID." }, "required": true, "description": "Native parent customer or job ListID, not a contact ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "wait", "immediate" ], "default": "wait", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." }, "required": false, "name": "completionMode", "in": "query", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$", "description": "Required stable app action ID. Reuse on retries with the identical payload; changed payloads return 409." }, "required": true, "description": "Required stable app action ID. Reuse on retries with the identical payload; changed payloads return 409.", "name": "Idempotency-Key", "in": "header" }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose durable pending contacts, serialized owner writes and connector IDs." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateQbdCustomerContactRequest" }, { "$ref": "#/components/schemas/TrackedContactCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks confirmed the customer/contact mutation. Inspect the write receipt and native status. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: pending person; direct: native owner modification operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Idempotency key was reused for a different mutation. Reconcile instead of blindly using a new key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Request body exceeds 8 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Native rejection or partial contact-save failure. Do not automatically retry with a new key/revision. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Appends one native person under an existing customer/job using CustomerMod/ContactsMod and the owner's revisionNumber. The request must not contain an existing person ID/revision. The receipt contains ALL returned contact identities; compare with the pre-write IDs to identify the addition, never guess from names. Supports name/title and the person's own email, phone and mobile (MainEmail/WorkPhone/Mobile); does not overwrite the owner's main email/phone or store CRM metadata. Inputs are trimmed; null/empty values and clearing fields are not supported. Requires qbd:write and a stable Idempotency-Key; same-key/same-payload retries replay the operation. Poll the connection operation with qbd:read until terminal: 202 is not success. Native 3200 is a revision conflict; native 582 means the parent may have changed but contact saving failed. Reconcile either outcome, never automatically replace revisions or resend under a new key. With mirror enabled, list /contacts?readMode=mirror&ownerType=customer|job&ownerId=...&afterOperationId=... until meta.projectionStatus=applied. The mirror contact id (ct_...) differs from nativeId. Webhooks are owner customer events, not independent contact events. This does not support vendor writes, deletion, primary/secondary selection or shared contacts across owners.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked mode returns PendingWriteReceipt and immediately indexes the person, including their own email/phone, even under a pending customer/job. Use the stable contact recordId for edits and document contactIds. A native ContactsRet.ListID is also accepted when the owner is confirmed. Email is not unique, even within one owner. Writes serialize through the owner's CustomerMod. Owner/contact revisions may be omitted in tracked mode: the connector captures the baseline at acceptance and checks it when dispatching, or uses the confirmed result of its preceding write. There is no blind latest-revision retry. Tracked updates may omit firstName. Native/direct mode retains its explicit native revision requirements.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/customers/{id}/contacts/{contactId}": { "post": { "summary": "Edit an additional contact on a QuickBooks customer or job", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Native parent customer or job ListID, not a contact ID." }, "required": true, "description": "Native parent customer or job ListID, not a contact ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 36, "pattern": "^(?!ct_)", "description": "Native ContactsRet.ListID: use the mirror contact's nativeId, NOT its opaque ct_ id." }, "required": true, "description": "Native ContactsRet.ListID: use the mirror contact's nativeId, NOT its opaque ct_ id.", "name": "contactId", "in": "path" }, { "schema": { "type": "string", "enum": [ "wait", "immediate" ], "default": "wait", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." }, "required": false, "name": "completionMode", "in": "query", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$", "description": "Required stable app action ID. Reuse on retries with the identical payload; changed payloads return 409." }, "required": true, "description": "Required stable app action ID. Reuse on retries with the identical payload; changed payloads return 409.", "name": "Idempotency-Key", "in": "header" }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose durable pending contacts, serialized owner writes and connector IDs." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/UpdateQbdCustomerContactRequest" }, { "$ref": "#/components/schemas/TrackedContactUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks confirmed the customer/contact mutation. Inspect the write receipt and native status. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: pending person; direct: native owner modification operation.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Idempotency key was reused for a different mutation. Reconcile instead of blindly using a new key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Request body exceeds 8 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Native rejection or partial contact-save failure. Do not automatically retry with a new key/revision. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Edits one existing native person. Requires the native person ID in the path, the owner's revisionNumber AND the person's contactRevisionNumber, and firstName. Never falls back to append. Send current name/title fields when editing; omitted communication fields are preserved. Supports name/title and the person's own email, phone and mobile (MainEmail/WorkPhone/Mobile); does not overwrite the owner's main email/phone or store CRM metadata. Inputs are trimmed; null/empty values and clearing fields are not supported. Requires qbd:write and a stable Idempotency-Key; same-key/same-payload retries replay the operation. Poll the connection operation with qbd:read until terminal: 202 is not success. Native 3200 is a revision conflict; native 582 means the parent may have changed but contact saving failed. Reconcile either outcome, never automatically replace revisions or resend under a new key. With mirror enabled, list /contacts?readMode=mirror&ownerType=customer|job&ownerId=...&afterOperationId=... until meta.projectionStatus=applied. The mirror contact id (ct_...) differs from nativeId. Webhooks are owner customer events, not independent contact events. This does not support vendor writes, deletion, primary/secondary selection or shared contacts across owners.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked mode returns PendingWriteReceipt and immediately indexes the person, including their own email/phone, even under a pending customer/job. Use the stable contact recordId for edits and document contactIds. A native ContactsRet.ListID is also accepted when the owner is confirmed. Email is not unique, even within one owner. Writes serialize through the owner's CustomerMod. Owner/contact revisions may be omitted in tracked mode: the connector captures the baseline at acceptance and checks it when dispatching, or uses the confirmed result of its preceding write. There is no blind latest-revision retry. Tracked updates may omit firstName. Native/direct mode retains its explicit native revision requirements.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/company": { "get": { "summary": "Retrieve QuickBooks Desktop company file info", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns detailed information about the connected QuickBooks company file, including company address, legal name, preferences, and subscribed services. Note that company information cannot be modified through the API, only through the QuickBooks Desktop user interface.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/bills-to-pay": { "get": { "summary": "List QuickBooks Desktop bills and credits available to pay", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "vendorId", "schema": { "type": "string", "maxLength": 36, "description": "The vendor whose open bills and available credits should be returned.", "example": "80000001-1234567890" }, "required": true, "description": "The vendor whose open bills and available credits should be returned." }, { "in": "query", "name": "payablesAccountId", "schema": { "description": "Filter for open bills and available credits assigned to this Accounts-Payable account. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "description": "Filter for open bills and available credits assigned to this Accounts-Payable account. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file." }, { "in": "query", "name": "dueDate", "schema": { "description": "Filter the bill branch to open bills due on or before this date, in ISO 8601 format (YYYY-MM-DD). If omitted, QuickBooks Desktop returns open bills from all due dates. Available credits can still be returned because credits do not have a due date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter the bill branch to open bills due on or before this date, in ISO 8601 format (YYYY-MM-DD). If omitted, QuickBooks Desktop returns open bills from all due dates. Available credits can still be returned because credits do not have a due date." }, { "in": "query", "name": "currencyIds", "schema": { "description": "Filter for open bills and available credits in these currencies.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter for open bills and available credits in these currencies." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists open vendor bills and available vendor credits for a specific QuickBooks Desktop vendor. Use each `bill.billId` as `applyToTransactions[].transactionId` in bill-payment requests. To apply a returned credit, place it under the target bill's `applyToTransactions[].applyCredits[]` entry, set `creditTransactionId` to `credit.creditTransactionId`, and choose an `appliedAmount` that does not exceed `credit.creditRemaining` or the target bill's remaining amount due.\n\n**NOTE:** QuickBooks Desktop does not support pagination for bills to pay; hence, there is no `cursor` parameter. Users typically have few bills to pay.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/payments-to-deposit": { "get": { "summary": "List QuickBooks Desktop payments available to deposit", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists received customer payments that are currently available to include in a QuickBooks Desktop deposit. Use each result's `paymentTransactionId` and, when present, `paymentTransactionLineId` as the corresponding fields on a deposit line.\n\n**NOTE:** QuickBooks Desktop does not support pagination for payments to deposit; hence, there is no `cursor` parameter. Users typically have few payments to deposit.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/preferences": { "get": { "summary": "Retrieve QuickBooks Desktop company preferences", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the preferences that the QuickBooks administrator has set for all users of the connected company file. Note that preferences cannot be modified through the API, only through the QuickBooks Desktop user interface.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/general-summary": { "get": { "summary": "Retrieve QuickBooks Desktop reports/general-summary", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "balance_sheet_by_class", "balance_sheet_previous_year_comparison", "balance_sheet_standard", "balance_sheet_summary", "customer_balance_summary", "expense_by_vendor_summary", "income_by_customer_summary", "inventory_stock_status_by_item", "inventory_stock_status_by_vendor", "income_tax_summary", "inventory_valuation_summary", "inventory_valuation_summary_by_site", "lot_number_in_stock_by_site", "physical_inventory_worksheet", "profit_and_loss_by_class", "profit_and_loss_by_job", "profit_and_loss_previous_year_comparison", "profit_and_loss_standard", "profit_and_loss_ytd_comparison", "purchase_by_item_summary", "purchase_by_vendor_summary", "sales_by_customer_summary", "sales_by_item_summary", "sales_by_sales_representative_summary", "sales_tax_liability", "sales_tax_revenue_summary", "serial_number_in_stock_by_site", "trial_balance", "vendor_balance_summary" ], "description": "The general summary report type to retrieve.", "example": "balance_sheet_by_class" }, "required": true, "description": "The general summary report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "transactionTypes", "schema": { "description": "Filter report rows by transaction type. Accepts one or more transaction types.", "example": [ "invoice", "sales_receipt" ], "type": "array", "items": { "type": "string", "enum": [ "all", "ar_refund_credit_card", "bill", "bill_payment_check", "bill_payment_credit_card", "build_assembly", "charge", "check", "credit_card_charge", "credit_card_credit", "credit_memo", "deposit", "estimate", "inventory_adjustment", "invoice", "item_receipt", "journal_entry", "liability_adjustment", "paycheck", "payroll_liability_check", "purchase_order", "receive_payment", "sales_order", "sales_receipt", "sales_tax_payment_check", "transfer", "vendor_credit", "ytd_adjustment" ] } }, "description": "Filter report rows by transaction type. Accepts one or more transaction types." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "reportCalendar", "schema": { "description": "The type of year to use for the report.", "example": "calendar_year", "type": "string", "enum": [ "calendar_year", "fiscal_year", "tax_year" ] }, "description": "The type of year to use for the report." }, { "in": "query", "name": "rowsToReturn", "schema": { "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows." }, { "in": "query", "name": "columnsToReturn", "schema": { "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns." }, { "in": "query", "name": "summarizeColumnsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report column headers.", "example": "month", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "description": "How QuickBooks Desktop calculates report data and labels report column headers." }, { "in": "query", "name": "includeSubcolumns", "schema": { "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values.", "example": true, "type": "boolean" }, "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values." }, { "in": "query", "name": "basis", "schema": { "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report.", "example": "accrual", "type": "string", "enum": [ "accrual", "cash", "none" ], "default": "none" }, "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop general summary report, such as a balance sheet, profit and loss, trial balance, sales, purchase, inventory, customer balance, vendor balance, sales tax, or income tax summary. This report is useful for aggregated financial or operational totals with optional date periods, filters, calendar settings, and column summarization.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/general-detail": { "get": { "summary": "Retrieve QuickBooks Desktop reports/general-detail", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "1099_detail", "audit_trail", "balance_sheet_detail", "check_detail", "customer_balance_detail", "deposit_detail", "estimates_by_job", "expense_by_vendor_detail", "general_ledger", "income_by_customer_detail", "income_tax_detail", "inventory_valuation_detail", "job_progress_invoices_vs_estimates", "journal", "missing_checks", "open_invoices", "open_purchase_orders", "open_purchase_orders_by_job", "open_sales_order_by_customer", "open_sales_order_by_item", "pending_sales", "profit_and_loss_detail", "purchase_by_item_detail", "purchase_by_vendor_detail", "sales_by_customer_detail", "sales_by_item_detail", "sales_by_sales_representative_detail", "transaction_detail_by_account", "transaction_list_by_customer", "transaction_list_by_date", "transaction_list_by_vendor", "unpaid_bills_detail", "unbilled_costs_by_job", "vendor_balance_detail" ], "description": "The general detail report type to retrieve.", "example": "1099_detail" }, "required": true, "description": "The general detail report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "transactionTypes", "schema": { "description": "Filter report rows by transaction type. Accepts one or more transaction types.", "example": [ "invoice", "sales_receipt" ], "type": "array", "items": { "type": "string", "enum": [ "all", "ar_refund_credit_card", "bill", "bill_payment_check", "bill_payment_credit_card", "build_assembly", "charge", "check", "credit_card_charge", "credit_card_credit", "credit_memo", "deposit", "estimate", "inventory_adjustment", "invoice", "item_receipt", "journal_entry", "liability_adjustment", "paycheck", "payroll_liability_check", "purchase_order", "receive_payment", "sales_order", "sales_receipt", "sales_tax_payment_check", "transfer", "vendor_credit", "ytd_adjustment" ] } }, "description": "Filter report rows by transaction type. Accepts one or more transaction types." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "accountsToInclude", "schema": { "description": "Whether to include all accounts or only accounts in use.", "example": "all", "type": "string", "enum": [ "all", "in_use" ] }, "description": "Whether to include all accounts or only accounts in use." }, { "in": "query", "name": "openBalanceAsOf", "schema": { "description": "The date through which QuickBooks Desktop calculates open balance information.", "example": "report_end_date", "type": "string", "enum": [ "report_end_date", "today" ], "default": "today" }, "description": "The date through which QuickBooks Desktop calculates open balance information." }, { "in": "query", "name": "summarizeRowsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report rows.", "example": "account", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "tax_line", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "description": "How QuickBooks Desktop calculates report data and labels report rows." }, { "in": "query", "name": "includeColumns", "schema": { "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here.", "example": [ "date", "transaction_type", "amount" ], "type": "array", "items": { "type": "string", "enum": [ "account", "aging", "amount", "amount_difference", "average_cost", "billed_date", "billing_status", "calculated_amount", "class", "cleared_status", "cost_price", "credit", "currency", "date", "debit", "delivery_date", "due_date", "estimate_active", "exchange_rate", "shipment_origin", "income_subject_to_tax", "invoiced", "item", "description", "last_modified_by", "latest_or_prior_state", "memo", "updated_at", "name", "name_account_number", "name_address", "name_city", "name_contact", "name_email", "name_fax", "name_phone", "name_state", "name_postal_code", "open_balance", "original_amount", "paid_amount", "paid_status", "paid_through_date", "payment_method", "payroll_item", "purchase_order_number", "print_status", "progress_amount", "progress_percent", "quantity", "quantity_available", "quantity_on_hand", "quantity_on_sales_order", "received_quantity", "ref_number", "running_balance", "sales_representative", "sales_tax_code", "serial_or_lot_number", "shipping_date", "shipping_method", "source_name", "split_account", "ssn_or_tax_identification_number", "tax_line", "tax_table_version", "terms", "transaction_id", "transaction_number", "transaction_type", "unit_price", "user_edit", "value_on_hand", "wage_base", "wage_base_tips" ] } }, "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here." }, { "in": "query", "name": "basis", "schema": { "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report.", "example": "accrual", "type": "string", "enum": [ "accrual", "cash", "none" ], "default": "none" }, "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop general detail report with transaction-level rows, such as General Ledger, Journal, Open Invoices, unpaid bills, sales detail, purchase detail, audit trail, and transaction lists. This report is useful for inspecting the transactions behind balances, receivables, payables, sales, purchases, inventory valuation, and audit activity, including report-only columns that may not be available from standard object queries.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/aging": { "get": { "summary": "Retrieve QuickBooks Desktop reports/aging", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "ap_aging_detail", "ap_aging_summary", "ar_aging_detail", "ar_aging_summary", "collections_report" ], "description": "The aging report type to retrieve.", "example": "ap_aging_detail" }, "required": true, "description": "The aging report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "transactionTypes", "schema": { "description": "Filter report rows by transaction type. Accepts one or more transaction types.", "example": [ "invoice", "sales_receipt" ], "type": "array", "items": { "type": "string", "enum": [ "all", "ar_refund_credit_card", "bill", "bill_payment_check", "bill_payment_credit_card", "build_assembly", "charge", "check", "credit_card_charge", "credit_card_credit", "credit_memo", "deposit", "estimate", "inventory_adjustment", "invoice", "item_receipt", "journal_entry", "liability_adjustment", "paycheck", "payroll_liability_check", "purchase_order", "receive_payment", "sales_order", "sales_receipt", "sales_tax_payment_check", "transfer", "vendor_credit", "ytd_adjustment" ] } }, "description": "Filter report rows by transaction type. Accepts one or more transaction types." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "includeColumns", "schema": { "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here.", "example": [ "date", "transaction_type", "amount" ], "type": "array", "items": { "type": "string", "enum": [ "account", "aging", "amount", "amount_difference", "average_cost", "billed_date", "billing_status", "calculated_amount", "class", "cleared_status", "cost_price", "credit", "currency", "date", "debit", "delivery_date", "due_date", "estimate_active", "exchange_rate", "shipment_origin", "income_subject_to_tax", "invoiced", "item", "description", "last_modified_by", "latest_or_prior_state", "memo", "updated_at", "name", "name_account_number", "name_address", "name_city", "name_contact", "name_email", "name_fax", "name_phone", "name_state", "name_postal_code", "open_balance", "original_amount", "paid_amount", "paid_status", "paid_through_date", "payment_method", "payroll_item", "purchase_order_number", "print_status", "progress_amount", "progress_percent", "quantity", "quantity_available", "quantity_on_hand", "quantity_on_sales_order", "received_quantity", "ref_number", "running_balance", "sales_representative", "sales_tax_code", "serial_or_lot_number", "shipping_date", "shipping_method", "source_name", "split_account", "ssn_or_tax_identification_number", "tax_line", "tax_table_version", "terms", "transaction_id", "transaction_number", "transaction_type", "unit_price", "user_edit", "value_on_hand", "wage_base", "wage_base_tips" ] } }, "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here." }, { "in": "query", "name": "accountsToInclude", "schema": { "description": "Whether to include all accounts or only accounts in use.", "example": "all", "type": "string", "enum": [ "all", "in_use" ] }, "description": "Whether to include all accounts or only accounts in use." }, { "in": "query", "name": "agingAsOf", "schema": { "description": "The date through which QuickBooks Desktop calculates aging information.", "example": "report_end_date", "type": "string", "enum": [ "report_end_date", "today" ], "default": "report_end_date" }, "description": "The date through which QuickBooks Desktop calculates aging information." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an accounts receivable, accounts payable, or collections aging report showing unpaid invoices and bills by aging criteria. This report is useful for analyzing receivables, payables, and collection work across summary or detail aging views.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/budget-summary": { "get": { "summary": "Retrieve QuickBooks Desktop reports/budget-summary", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "balance_sheet_budget_overview", "balance_sheet_budget_vs_actual", "profit_and_loss_budget_overview", "profit_and_loss_budget_performance", "profit_and_loss_budget_vs_actual" ], "description": "The budget summary report type to retrieve.", "example": "balance_sheet_budget_overview" }, "required": true, "description": "The budget summary report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "fiscalYear", "schema": { "type": "number", "description": "The fiscal year of the QuickBooks budget. QuickBooks Desktop returns the full fiscal year for prior years and year-to-date data for the current fiscal year.", "example": 2026 }, "required": true, "description": "The fiscal year of the QuickBooks budget. QuickBooks Desktop returns the full fiscal year for prior years and year-to-date data for the current fiscal year." }, { "in": "query", "name": "budgetCriterion", "schema": { "description": "What the budget covers, such as accounts, accounts and classes, or accounts and customers.", "example": "accounts", "type": "string", "enum": [ "accounts", "accounts_and_classes", "accounts_and_customers" ] }, "description": "What the budget covers, such as accounts, accounts and classes, or accounts and customers." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "summarizeColumnsBy", "schema": { "description": "How QuickBooks Desktop calculates budget report columns and labels column headers.", "example": "date", "type": "string", "enum": [ "class", "customer", "date" ] }, "description": "How QuickBooks Desktop calculates budget report columns and labels column headers." }, { "in": "query", "name": "summarizeRowsBy", "schema": { "description": "How QuickBooks Desktop labels budget report rows.", "example": "account", "type": "string", "enum": [ "account", "class", "customer" ] }, "description": "How QuickBooks Desktop labels budget report rows." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop budget summary report for Balance Sheet or Profit and Loss budgets, including budget overview, budget versus actual, and performance views. This report compares budgeted amounts against actual activity for a fiscal year and budget criterion; the target budget must already exist in QuickBooks Desktop.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/job": { "get": { "summary": "Retrieve QuickBooks Desktop reports/job", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "item_estimates_vs_actuals", "item_profitability", "job_estimates_vs_actuals_detail", "job_estimates_vs_actuals_summary", "job_profitability_detail", "job_profitability_summary" ], "description": "The job report type to retrieve.", "example": "item_estimates_vs_actuals" }, "required": true, "description": "The job report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "transactionTypes", "schema": { "description": "Filter report rows by transaction type. Accepts one or more transaction types.", "example": [ "invoice", "sales_receipt" ], "type": "array", "items": { "type": "string", "enum": [ "all", "ar_refund_credit_card", "bill", "bill_payment_check", "bill_payment_credit_card", "build_assembly", "charge", "check", "credit_card_charge", "credit_card_credit", "credit_memo", "deposit", "estimate", "inventory_adjustment", "invoice", "item_receipt", "journal_entry", "liability_adjustment", "paycheck", "payroll_liability_check", "purchase_order", "receive_payment", "sales_order", "sales_receipt", "sales_tax_payment_check", "transfer", "vendor_credit", "ytd_adjustment" ] } }, "description": "Filter report rows by transaction type. Accepts one or more transaction types." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "summarizeColumnsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report column headers.", "example": "month", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "description": "How QuickBooks Desktop calculates report data and labels report column headers." }, { "in": "query", "name": "includeSubcolumns", "schema": { "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values.", "example": true, "type": "boolean" }, "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop job report for estimates versus actuals, item profitability, or job profitability. This report is useful for project costing, margin analysis, and estimate tracking by customer or job; job profitability detail and estimates-versus-actuals detail report types require a customer or job filter.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/time": { "get": { "summary": "Retrieve QuickBooks Desktop reports/time", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "time_by_item", "time_by_job_detail", "time_by_job_summary", "time_by_name" ], "description": "The time report type to retrieve.", "example": "time_by_item" }, "required": true, "description": "The time report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "summarizeColumnsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report column headers.", "example": "month", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "description": "How QuickBooks Desktop calculates report data and labels report column headers." }, { "in": "query", "name": "includeSubcolumns", "schema": { "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values.", "example": true, "type": "boolean" }, "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values." }, { "in": "query", "name": "reportCalendar", "schema": { "description": "The type of year to use for the report.", "example": "calendar_year", "type": "string", "enum": [ "calendar_year", "fiscal_year", "tax_year" ] }, "description": "The type of year to use for the report." }, { "in": "query", "name": "rowsToReturn", "schema": { "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows." }, { "in": "query", "name": "columnsToReturn", "schema": { "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop time report by item, job, or name, with summary or detail rows depending on the selected report type. This report is useful for analyzing tracked time for billing, costing, staffing, or project review.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/custom-detail": { "get": { "summary": "Retrieve QuickBooks Desktop reports/custom-detail", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "description": "The custom detail report type to retrieve. This endpoint supports only `custom_transaction_detail`, so this parameter is optional and defaults to `custom_transaction_detail`.", "example": "custom_transaction_detail", "default": "custom_transaction_detail", "type": "string", "enum": [ "custom_transaction_detail" ] }, "description": "The custom detail report type to retrieve. This endpoint supports only `custom_transaction_detail`, so this parameter is optional and defaults to `custom_transaction_detail`." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "transactionTypes", "schema": { "description": "Filter report rows by transaction type. Accepts one or more transaction types.", "example": [ "invoice", "sales_receipt" ], "type": "array", "items": { "type": "string", "enum": [ "all", "ar_refund_credit_card", "bill", "bill_payment_check", "bill_payment_credit_card", "build_assembly", "charge", "check", "credit_card_charge", "credit_card_credit", "credit_memo", "deposit", "estimate", "inventory_adjustment", "invoice", "item_receipt", "journal_entry", "liability_adjustment", "paycheck", "payroll_liability_check", "purchase_order", "receive_payment", "sales_order", "sales_receipt", "sales_tax_payment_check", "transfer", "vendor_credit", "ytd_adjustment" ] } }, "description": "Filter report rows by transaction type. Accepts one or more transaction types." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "accountsToInclude", "schema": { "description": "Whether to include all accounts or only accounts in use.", "example": "all", "type": "string", "enum": [ "all", "in_use" ] }, "description": "Whether to include all accounts or only accounts in use." }, { "in": "query", "name": "openBalanceAsOf", "schema": { "description": "The date through which QuickBooks Desktop calculates open balance information.", "example": "report_end_date", "type": "string", "enum": [ "report_end_date", "today" ], "default": "today" }, "description": "The date through which QuickBooks Desktop calculates open balance information." }, { "in": "query", "name": "summarizeRowsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report rows.", "example": "account", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "tax_line", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "required": true, "description": "How QuickBooks Desktop calculates report data and labels report rows." }, { "in": "query", "name": "includeColumns", "schema": { "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here.", "example": [ "date", "transaction_type", "amount" ], "type": "array", "items": { "type": "string", "enum": [ "account", "aging", "amount", "amount_difference", "average_cost", "billed_date", "billing_status", "calculated_amount", "class", "cleared_status", "cost_price", "credit", "currency", "date", "debit", "delivery_date", "due_date", "estimate_active", "exchange_rate", "shipment_origin", "income_subject_to_tax", "invoiced", "item", "description", "last_modified_by", "latest_or_prior_state", "memo", "updated_at", "name", "name_account_number", "name_address", "name_city", "name_contact", "name_email", "name_fax", "name_phone", "name_state", "name_postal_code", "open_balance", "original_amount", "paid_amount", "paid_status", "paid_through_date", "payment_method", "payroll_item", "purchase_order_number", "print_status", "progress_amount", "progress_percent", "quantity", "quantity_available", "quantity_on_hand", "quantity_on_sales_order", "received_quantity", "ref_number", "running_balance", "sales_representative", "sales_tax_code", "serial_or_lot_number", "shipping_date", "shipping_method", "source_name", "split_account", "ssn_or_tax_identification_number", "tax_line", "tax_table_version", "terms", "transaction_id", "transaction_number", "transaction_type", "unit_price", "user_edit", "value_on_hand", "wage_base", "wage_base_tips" ] } }, "required": true, "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here." }, { "in": "query", "name": "basis", "schema": { "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report.", "example": "accrual", "type": "string", "enum": [ "accrual", "cash", "none" ], "default": "none" }, "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a custom transaction detail report built from the row grouping, included columns, date period, and filters you request. This report is useful when no preset detail report exposes the transaction rows or report-only columns you need; QuickBooks Desktop does not choose default columns for this report.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/custom-summary": { "get": { "summary": "Retrieve QuickBooks Desktop reports/custom-summary", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "description": "The custom summary report type to retrieve. This endpoint supports only `custom_summary`, so this parameter is optional and defaults to `custom_summary`.", "example": "custom_summary", "default": "custom_summary", "type": "string", "enum": [ "custom_summary" ] }, "description": "The custom summary report type to retrieve. This endpoint supports only `custom_summary`, so this parameter is optional and defaults to `custom_summary`." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "transactionTypes", "schema": { "description": "Filter report rows by transaction type. Accepts one or more transaction types.", "example": [ "invoice", "sales_receipt" ], "type": "array", "items": { "type": "string", "enum": [ "all", "ar_refund_credit_card", "bill", "bill_payment_check", "bill_payment_credit_card", "build_assembly", "charge", "check", "credit_card_charge", "credit_card_credit", "credit_memo", "deposit", "estimate", "inventory_adjustment", "invoice", "item_receipt", "journal_entry", "liability_adjustment", "paycheck", "payroll_liability_check", "purchase_order", "receive_payment", "sales_order", "sales_receipt", "sales_tax_payment_check", "transfer", "vendor_credit", "ytd_adjustment" ] } }, "description": "Filter report rows by transaction type. Accepts one or more transaction types." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "reportCalendar", "schema": { "description": "The type of year to use for the report.", "example": "calendar_year", "type": "string", "enum": [ "calendar_year", "fiscal_year", "tax_year" ] }, "description": "The type of year to use for the report." }, { "in": "query", "name": "rowsToReturn", "schema": { "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows." }, { "in": "query", "name": "columnsToReturn", "schema": { "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns." }, { "in": "query", "name": "summarizeColumnsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report column headers.", "example": "month", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "required": true, "description": "How QuickBooks Desktop calculates report data and labels report column headers." }, { "in": "query", "name": "summarizeRowsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report rows.", "example": "account", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "tax_line", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "required": true, "description": "How QuickBooks Desktop calculates report data and labels report rows." }, { "in": "query", "name": "includeSubcolumns", "schema": { "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values.", "example": true, "type": "boolean" }, "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values." }, { "in": "query", "name": "basis", "schema": { "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report.", "example": "accrual", "type": "string", "enum": [ "accrual", "cash", "none" ], "default": "none" }, "description": "The accounting basis to use for the report. Use `cash` to base income and expenses on when money changes hands, `accrual` to base them on invoice and bill dates, or `none` to use the QuickBooks Desktop default for the report." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a custom summary report built from the row and column axes, filters, date period, calendar, and basis options you request. This report is useful when preset summary reports do not match the dimensions you need; QuickBooks Desktop does not assume a default layout.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/payroll-detail": { "get": { "summary": "Retrieve QuickBooks Desktop reports/payroll-detail", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "employee_state_taxes_detail", "payroll_item_detail", "payroll_review_detail", "payroll_transaction_detail", "payroll_transactions_by_payee" ], "description": "The payroll detail report type to retrieve.", "example": "employee_state_taxes_detail" }, "required": true, "description": "The payroll detail report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "accountsToInclude", "schema": { "description": "Whether to include all accounts or only accounts in use.", "example": "all", "type": "string", "enum": [ "all", "in_use" ] }, "description": "Whether to include all accounts or only accounts in use." }, { "in": "query", "name": "openBalanceAsOf", "schema": { "description": "The date through which QuickBooks Desktop calculates open balance information.", "example": "report_end_date", "type": "string", "enum": [ "report_end_date", "today" ], "default": "today" }, "description": "The date through which QuickBooks Desktop calculates open balance information." }, { "in": "query", "name": "summarizeRowsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report rows.", "example": "account", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "tax_line", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "description": "How QuickBooks Desktop calculates report data and labels report rows." }, { "in": "query", "name": "includeColumns", "schema": { "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here.", "example": [ "date", "transaction_type", "amount" ], "type": "array", "items": { "type": "string", "enum": [ "account", "aging", "amount", "amount_difference", "average_cost", "billed_date", "billing_status", "calculated_amount", "class", "cleared_status", "cost_price", "credit", "currency", "date", "debit", "delivery_date", "due_date", "estimate_active", "exchange_rate", "shipment_origin", "income_subject_to_tax", "invoiced", "item", "description", "last_modified_by", "latest_or_prior_state", "memo", "updated_at", "name", "name_account_number", "name_address", "name_city", "name_contact", "name_email", "name_fax", "name_phone", "name_state", "name_postal_code", "open_balance", "original_amount", "paid_amount", "paid_status", "paid_through_date", "payment_method", "payroll_item", "purchase_order_number", "print_status", "progress_amount", "progress_percent", "quantity", "quantity_available", "quantity_on_hand", "quantity_on_sales_order", "received_quantity", "ref_number", "running_balance", "sales_representative", "sales_tax_code", "serial_or_lot_number", "shipping_date", "shipping_method", "source_name", "split_account", "ssn_or_tax_identification_number", "tax_line", "tax_table_version", "terms", "transaction_id", "transaction_number", "transaction_type", "unit_price", "user_edit", "value_on_hand", "wage_base", "wage_base_tips" ] } }, "description": "The report columns to include, by column type. Accepts one or more columns.\n\n**IMPORTANT**: When this parameter is present, QuickBooks Desktop omits its default report columns unless you include them here." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop payroll detail report, including employee state tax detail, payroll item detail, payroll review detail, payroll transaction detail, and payroll transactions by payee. This report is useful for auditing paycheck line items, payroll item usage, tax calculations, and payee-level payroll activity.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/reports/payroll-summary": { "get": { "summary": "Retrieve QuickBooks Desktop reports/payroll-summary", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "query", "name": "reportType", "schema": { "type": "string", "enum": [ "employee_earnings_summary", "payroll_liability_balances", "payroll_summary" ], "description": "The payroll summary report type to retrieve.", "example": "employee_earnings_summary" }, "required": true, "description": "The payroll summary report type to retrieve." }, { "in": "query", "name": "reportDateFrom", "schema": { "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateTo", "schema": { "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows dated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`. If you omit `reportDateFrom`, `reportDateTo`, and `reportDateMacro`, QuickBooks Desktop uses the current fiscal year to date." }, { "in": "query", "name": "reportDateMacro", "schema": { "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`.", "example": "this_year_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative date macro for the report period. Choose either `reportDateMacro` or `reportDateFrom`/`reportDateTo`." }, { "in": "query", "name": "accountType", "schema": { "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "allowed_for_1099", "ap_and_sales_tax", "ap_or_credit_card", "ar_and_ap", "asset", "balance_sheet", "bank", "bank_and_ar_and_ap_and_uf", "bank_and_uf", "cost_of_sales", "credit_card", "current_asset", "current_asset_and_expense", "current_liability", "equity", "equity_and_income_and_expense", "expense_and_other_expense", "fixed_asset", "income_and_expense", "income_and_other_income", "liability", "liability_and_equity", "long_term_liability", "non_posting", "ordinary_expense", "ordinary_income", "ordinary_income_and_cogs", "ordinary_income_and_expense", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income", "other_income_or_expense" ] }, "description": "Filter report rows by account type. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountIds", "schema": { "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned account IDs. Accepts one or more account IDs. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "accountFullNames", "schema": { "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`.", "example": [ "Corporate:Accounts-Payable" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by account `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more account full names. Choose only one account filter per request: `accountType`, `accountIds`, or `accountFullNames`." }, { "in": "query", "name": "entityType", "schema": { "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": "customer", "type": "string", "enum": [ "customer", "employee", "other_name", "vendor" ] }, "description": "Filter report rows by entity type, such as customer, vendor, employee, or other name. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityIds", "schema": { "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned entity IDs. Accepts one or more entity IDs. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "entityFullNames", "schema": { "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`.", "example": [ "ABC Corporation:Website Redesign Project" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by entity `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more entity full names. Choose only one entity filter per request: `entityType`, `entityIds`, or `entityFullNames`." }, { "in": "query", "name": "itemType", "schema": { "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": "inventory", "type": "string", "enum": [ "all_except_fixed_asset", "assembly", "discount", "fixed_asset", "inventory", "inventory_and_assembly", "non_inventory", "other_charge", "payment", "sales", "sales_tax", "service" ] }, "description": "Filter report rows by item type. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemIds", "schema": { "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned item IDs. Accepts one or more item IDs. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "itemFullNames", "schema": { "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`.", "example": [ "Services:Consulting" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by item `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more item full names. Choose only one item filter per request: `itemType`, `itemIds`, or `itemFullNames`." }, { "in": "query", "name": "classIds", "schema": { "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "80000001-1234567890" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by QuickBooks-assigned class IDs. Accepts one or more class IDs. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "classFullNames", "schema": { "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`.", "example": [ "Department:Marketing" ], "type": "array", "items": { "type": "string" } }, "description": "Filter report rows by class `fullName` values, case-insensitive. A `fullName` is a fully qualified QuickBooks name formed by joining parent object names with the object's `name` using colons. Accepts one or more class full names. Choose only one class filter per request: `classIds` or `classFullNames`." }, { "in": "query", "name": "detailLevel", "schema": { "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows.", "example": "all_except_summary", "type": "string", "enum": [ "all", "all_except_summary", "summary_only" ], "default": "all" }, "description": "The report detail level to include. Use `all` for all rows, `all_except_summary` to omit summary rows, or `summary_only` to return only summary rows." }, { "in": "query", "name": "postingStatus", "schema": { "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register.", "example": "posting", "type": "string", "enum": [ "either", "non_posting", "posting" ] }, "description": "Filter report rows that are posting, non-posting, or either. Posting status refers to whether QuickBooks records the transaction in an account register." }, { "in": "query", "name": "updatedAfter", "schema": { "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-01-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or after this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedBefore", "schema": { "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "2025-02-01", "type": "string", "format": "date" }, "description": "Filter report rows updated on or before this date, in ISO 8601 format (YYYY-MM-DD). Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "updatedDateMacro", "schema": { "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`.", "example": "this_month_to_date", "type": "string", "enum": [ "all", "today", "this_week", "this_week_to_date", "this_month", "this_month_to_date", "this_quarter", "this_quarter_to_date", "this_year", "this_year_to_date", "yesterday", "last_week", "last_week_to_date", "last_month", "last_month_to_date", "last_quarter", "last_quarter_to_date", "last_year", "last_year_to_date", "next_week", "next_four_weeks", "next_month", "next_quarter", "next_year" ] }, "description": "A QuickBooks Desktop relative updated-date macro. Choose either `updatedDateMacro` or `updatedAfter`/`updatedBefore`." }, { "in": "query", "name": "reportCalendar", "schema": { "description": "The type of year to use for the report.", "example": "calendar_year", "type": "string", "enum": [ "calendar_year", "fiscal_year", "tax_year" ] }, "description": "The type of year to use for the report." }, { "in": "query", "name": "rowsToReturn", "schema": { "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report rows QuickBooks returns. Use `active_only` for active rows, `non_zero` for rows with non-zero values, or `all` for all rows." }, { "in": "query", "name": "columnsToReturn", "schema": { "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns.", "example": "all", "type": "string", "enum": [ "active_only", "non_zero", "all" ] }, "description": "Filters which report columns QuickBooks returns. Use `active_only` for active columns, `non_zero` for columns with non-zero values, or `all` for all columns." }, { "in": "query", "name": "summarizeColumnsBy", "schema": { "description": "How QuickBooks Desktop calculates report data and labels report column headers.", "example": "month", "type": "string", "enum": [ "account", "balance_sheet", "class", "customer", "customer_type", "day", "employee", "four_week", "half_month", "income_statement", "item_detail", "item_type", "month", "payee", "payment_method", "payroll_item_detail", "payroll_ytd_detail", "quarter", "sales_representative", "sales_tax_code", "shipping_method", "terms", "total_only", "two_week", "vendor", "vendor_type", "week", "year" ] }, "description": "How QuickBooks Desktop calculates report data and labels report column headers." }, { "in": "query", "name": "includeSubcolumns", "schema": { "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values.", "example": true, "type": "boolean" }, "description": "Whether to include subcolumns in the report.\n\n**NOTE**: QuickBooks Desktop may still omit subcolumns that it can easily compute from other returned values." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a QuickBooks Desktop payroll summary report, including payroll totals by employee, employee earnings by payroll item, and payroll liability balances. This report is useful for wage, tax, deduction, addition, employer contribution, and unpaid payroll liability reporting.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/account-tax-lines": { "get": { "summary": "List QuickBooks Desktop account-tax-lines", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of account tax lines.\n\n**NOTE:** QuickBooks Desktop does not support pagination for account tax lines; hence, there is no `cursor` parameter. Users typically have few account tax lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/accounts": { "get": { "summary": "List QuickBooks Desktop accounts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of accounts.\n\n**NOTE:** QuickBooks Desktop does not support pagination for accounts; hence, there is no `cursor` parameter. Users typically have few accounts.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop accounts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this account. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two accounts could both have the `name` \"Accounts-Payable\", but they could have unique `fullName` values, such as \"Corporate:Accounts-Payable\" and \"Finance:Accounts-Payable\".\n\nMaximum length: 31 characters.", "example": "Accounts-Payable" }, "isActive": { "description": "Indicates whether this account 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 account one level above this one in the hierarchy. For example, if this account has a `fullName` of \"Corporate:Accounts-Payable\", its parent has a `fullName` of \"Corporate\". If this account is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "accountType": { "description": "The classification of this account, indicating its purpose within the chart of accounts.\n\n**NOTE**: You cannot create an account of type `non_posting` through the API because QuickBooks creates these accounts behind the scenes.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "bank", "cost_of_goods_sold", "credit_card", "equity", "expense", "fixed_asset", "income", "long_term_liability", "non_posting", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income" ] }, "accountNumber": { "description": "The account'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" }, "bankAccountNumber": { "description": "The bank account number or identifying note for this account. Access to this field may be restricted based on permissions.", "example": "123456789", "type": "string" }, "description": { "description": "A description of this account.", "example": "Accounts-payable are the amounts owed to suppliers for goods and services purchased on credit.", "type": "string" }, "openingBalance": { "description": "The amount of money in, or the value of, this account as of `openingBalanceDate`. On a bank statement, this would be the amount of money in the account at the beginning of the statement period.", "example": "1000.00", "type": "string" }, "openingBalanceDate": { "description": "The date of the opening balance of this account, 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 account, 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 }, "taxLineId": { "type": "number", "description": "The identifier of the tax line associated with this account. You can see a list of all available values for this field by calling the endpoint for account tax lines.", "example": 123 }, "currencyId": { "description": "The account'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", "accountType" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new financial account. QuickBooks requires you to pick a supported account type for the chart of accounts, and non-posting types can’t be created through the API.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/accounts/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop accounts record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an account by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific accounts by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop accounts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the account to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the account to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the account 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 account. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two accounts could both have the `name` \"Accounts-Payable\", but they could have unique `fullName` values, such as \"Corporate:Accounts-Payable\" and \"Finance:Accounts-Payable\".\n\nMaximum length: 31 characters.", "example": "Accounts-Payable", "type": "string", "maxLength": 31 }, "isActive": { "description": "Indicates whether this account is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "parentId": { "description": "The parent account one level above this one in the hierarchy. For example, if this account has a `fullName` of \"Corporate:Accounts-Payable\", its parent has a `fullName` of \"Corporate\". If this account is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "accountType": { "description": "The classification of this account, indicating its purpose within the chart of accounts.\n\n**NOTE**: You cannot create an account of type `non_posting` through the API because QuickBooks creates these accounts behind the scenes.", "example": "bank", "type": "string", "enum": [ "accounts_payable", "accounts_receivable", "bank", "cost_of_goods_sold", "credit_card", "equity", "expense", "fixed_asset", "income", "long_term_liability", "non_posting", "other_asset", "other_current_asset", "other_current_liability", "other_expense", "other_income" ] }, "accountNumber": { "description": "The account'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" }, "bankAccountNumber": { "description": "The bank account number or identifying note for this account. Access to this field may be restricted based on permissions.", "example": "123456789", "type": "string" }, "description": { "description": "A description of this account.", "example": "Accounts-payable are the amounts owed to suppliers for goods and services purchased on credit.", "type": "string" }, "openingBalance": { "description": "The amount of money in, or the value of, this account as of `openingBalanceDate`. On a bank statement, this would be the amount of money in the account at the beginning of the statement period.", "example": "1000.00", "type": "string" }, "openingBalanceDate": { "description": "The date of the opening balance of this account, 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 account, 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 }, "taxLineId": { "type": "number", "description": "The identifier of the tax line associated with this account. You can see a list of all available values for this field by calling the endpoint for account tax lines.", "example": 123 }, "currencyId": { "description": "The account'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": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing financial account. You can rename the account, adjust numbering, or change supported attributes, but QuickBooks won’t let you convert it to a non-posting type via the API.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bill-check-payments": { "get": { "summary": "List QuickBooks Desktop bill-check-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of bill check payments. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop bill-check-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "description": "The vendor who sent the bill(s) that this bill check payment is paying and who will receive this payment.\n\n**IMPORTANT**: This vendor must match the `vendor` on the bill(s) specified in `applyToTransactions`; otherwise, QuickBooks will say the `transactionId` in `applyToTransactions` \"does not exist\".", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this bill check payment is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this bill check payment is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this bill check payment, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "bankAccountId": { "description": "The bank account from which the funds are being drawn for this bill check payment; e.g., Checking or Savings. This bill check payment will decrease the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this bill check payment is included in the queue of documents for QuickBooks to print.", "example": true }, "refNumber": { "description": "The case-sensitive user-defined reference number for this bill check payment, 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\n**IMPORTANT**: For checks, this field is the check number.\n\nMaximum length: 11 characters.", "example": "CHECK-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this bill check payment.", "example": "Payment for office supplies - Invoice INV-1234", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this bill check payment'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" }, "applyToTransactions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the target transaction to which this payment is applied.", "example": "123ABC-1234567890" }, "paymentAmount": { "description": "The monetary amount to apply to the target 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": "25.00", "type": "string" }, "applyCredits": { "description": "Credits to apply to this target transaction, reducing its balance. This creates a link between this target transaction 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 target transaction and check the `linkedTransactions` response field. If fetching a list of target transactions, 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 } }, "discountAmount": { "description": "The monetary amount by which to reduce this target transaction's balance, 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": "50.00", "type": "string" }, "discountAccountId": { "description": "The financial account used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "discountClassId": { "description": "The class used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "transactionId" ], "additionalProperties": false }, "description": "The bills to be paid by this bill check payment. This will create a link between this bill check payment and the specified bills.\n\n**IMPORTANT**: In each `applyToTransactions` object, you must specify either `paymentAmount`, `applyCredits`, `discountAmount`, or any combination of these; if none of these are specified, you will receive an error for an empty transaction.\n\n**IMPORTANT**: The target bill must have `isPaid=false`, otherwise, QuickBooks will report this object as \"cannot be found\"." } }, "required": [ "vendorId", "transactionDate", "bankAccountId", "applyToTransactions" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Records a check payment against one vendor’s open bills. Each bill allocation must include a payment amount, discount, or vendor credit, and the accounts payable account has to match the one used on the bills you’re closing.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bill-check-payments/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop bill-check-payments record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a bill check payment by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific bill check payments by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop bill-check-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill check payment to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill check payment to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the bill check payment 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" }, "transactionDate": { "description": "The date of this bill check payment, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "bankAccountId": { "description": "The bank account from which the funds are being drawn for this bill check payment; e.g., Checking or Savings. This bill check payment will decrease the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this bill check payment, 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": "1000.00", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this bill check payment'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" }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this bill check payment is included in the queue of documents for QuickBooks to print.", "example": true }, "refNumber": { "description": "The case-sensitive user-defined reference number for this bill check payment, 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\n**IMPORTANT**: For checks, this field is the check number.\n\nMaximum length: 11 characters.", "example": "CHECK-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this bill check payment.", "example": "Payment for office supplies - Invoice INV-1234", "type": "string" }, "applyToTransactions": { "description": "The bills to be paid by this bill check payment. This will create a link between this bill check payment and the specified bills.\n\n**IMPORTANT**: In each `applyToTransactions` object, you must specify either `paymentAmount`, `applyCredits`, `discountAmount`, or any combination of these; if none of these are specified, you will receive an error for an empty transaction.\n\n**IMPORTANT**: The target bill must have `isPaid=false`, otherwise, QuickBooks will report this object as \"cannot be found\".", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the target transaction to which this payment is applied.", "example": "123ABC-1234567890" }, "paymentAmount": { "description": "The monetary amount to apply to the target 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": "25.00", "type": "string" }, "applyCredits": { "description": "Credits to apply to this target transaction, reducing its balance. This creates a link between this target transaction 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 target transaction and check the `linkedTransactions` response field. If fetching a list of target transactions, 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 } }, "discountAmount": { "description": "The monetary amount by which to reduce this target transaction's balance, 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": "50.00", "type": "string" }, "discountAccountId": { "description": "The financial account used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "discountClassId": { "description": "The class used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "transactionId" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a bill check payment so you can reallocate how amounts, discounts, or credits are applied to the vendor’s bills. When you update a payment, QuickBooks clears the prior allocations but keeps any existing vendor credits unchanged, so submit the full list of bill applications in this request.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop bill-check-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill check payment to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill check payment to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a bill check payment. The deletion will fail if the bill check payment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bill-credit-card-payments": { "get": { "summary": "List QuickBooks Desktop bill-credit-card-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of bill credit card payments. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop bill-credit-card-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "description": "The vendor who sent the bill(s) that this bill credit card payment is paying and who will receive this payment.\n\n**IMPORTANT**: This vendor must match the `vendor` on the bill(s) specified in `applyToTransactions`; otherwise, QuickBooks will say the `transactionId` in `applyToTransactions` \"does not exist\".", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this bill credit card payment is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this bill credit card payment is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this bill credit card payment, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "creditCardAccountId": { "description": "The credit card account to which this bill credit card payment is being charged. This bill credit card payment will decrease the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "refNumber": { "description": "The case-sensitive user-defined reference number for this bill credit card payment, 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": "CARD-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this bill credit card payment.", "example": "Payment for office supplies - Invoice INV-1234", "type": "string" }, "exchangeRate": { "description": "The market exchange rate between this bill credit card payment'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" }, "applyToTransactions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the target transaction to which this payment is applied.", "example": "123ABC-1234567890" }, "paymentAmount": { "description": "The monetary amount to apply to the target 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": "25.00", "type": "string" }, "applyCredits": { "description": "Credits to apply to this target transaction, reducing its balance. This creates a link between this target transaction 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 target transaction and check the `linkedTransactions` response field. If fetching a list of target transactions, 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 } }, "discountAmount": { "description": "The monetary amount by which to reduce this target transaction's balance, 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": "50.00", "type": "string" }, "discountAccountId": { "description": "The financial account used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "discountClassId": { "description": "The class used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "transactionId" ], "additionalProperties": false }, "description": "The bills to be paid by this bill credit card payment. This will create a link between this bill credit card payment and the specified bills.\n\n**IMPORTANT**: In each `applyToTransactions` object, you must specify either `paymentAmount`, `applyCredits`, `discountAmount`, or any combination of these; if none of these are specified, you will receive an error for an empty transaction.\n\n**IMPORTANT**: The target bill must have `isPaid=false`, otherwise, QuickBooks will report this object as \"cannot be found\"." } }, "required": [ "vendorId", "transactionDate", "creditCardAccountId", "applyToTransactions" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Charges one vendor’s bills to a credit card account. Each bill allocation must supply a payment amount, discount, or credit, and you have to use the same accounts payable account that’s on the bills being closed.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bill-credit-card-payments/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop bill-credit-card-payments record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a bill credit card payment by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific bill credit card payments by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "delete": { "summary": "Delete QuickBooks Desktop bill-credit-card-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill credit card payment to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill credit card payment to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a bill credit card payment. The deletion will fail if the bill credit card payment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bills": { "get": { "summary": "List QuickBooks Desktop bills", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "enum": [ "all", "paid", "unpaid" ], "description": "Filters payable or receivable transactions by paid, unpaid, or all payment status." }, "required": false, "name": "paymentStatus", "in": "query", "description": "Filters payable or receivable transactions by paid, unpaid, or all payment status." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of bills. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create bill in QuickBooks Desktop", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "description": "The vendor who sent this bill for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "vendorAddress": { "description": "The address of the vendor who sent this bill.", "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 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this bill is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this bill is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this bill, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "dueDate": { "description": "The date by which this bill must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this bill, 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: 20 characters.", "example": "BILL-1234", "type": "string", "maxLength": 20 }, "termsId": { "description": "The bill's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this bill that appears in the Accounts-Payable register and in reports that include this bill.", "example": "Office supplies for September", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this bill, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the bill's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this bill'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 purchase orders that you wish to link to this bill. 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 bill's lines, if available.\n\nTransactions can only be linked when creating this bill and cannot be unlinked later.\n\nYou can use both `linkToTransactionIds` (on this bill) 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 bill and check the `linkedTransactions` response field. If fetching a list of bills, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 36 } }, "expenseLines": { "description": "The bill's expense lines, each representing one line in this expense.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the expense 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 } }, "itemLines": { "description": "The bill's item lines, each representing the purchase of a specific item or service.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this item 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. If the parent transaction is a bill or an item receipt, you can only link to purchase orders; QuickBooks does not support linking these transactions to other transaction types.\n\nTransaction lines can only be linked when creating this item line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this item 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 item 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 transaction and check the `linkedTransactions` response field. If fetching a list of transactions, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "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 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item 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 } }, "itemGroupLines": { "description": "The bill's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this item group 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 group associated with this item group line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item group 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 } } }, "required": [ "itemGroupId" ], "additionalProperties": false } } }, "required": [ "vendorId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the bill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks write is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the bill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a vendor bill and posts it to accounts payable. You can also link eligible purchase orders so QuickBooks pulls their lines onto the bill before it's saved.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bills/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop bills record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a bill by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific bills by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop bills", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the bill 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" }, "vendorId": { "description": "The vendor who sent this bill for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "vendorAddress": { "description": "The address of the vendor who sent this bill.", "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 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this bill is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this bill is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this bill, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "dueDate": { "description": "The date by which this bill must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this bill, 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: 20 characters.", "example": "BILL-1234", "type": "string", "maxLength": 20 }, "termsId": { "description": "The bill's payment terms, defining when payment is due and any applicable discounts.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this bill that appears in the Accounts-Payable register and in reports that include this bill.", "example": "Office supplies for September", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this bill, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the bill's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this bill'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" }, "clearExpenseLines": { "description": "When `true`, removes all existing expense lines associated with this bill. To modify or add individual expense lines, use the field `expenseLines` instead.", "example": false, "type": "boolean" }, "expenseLines": { "description": "The bill's expense lines, each representing one line in this expense.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing expense lines for the bill with this array. To keep any existing expense lines, you must include them in this array even if they have not changed. **Any expense lines not included will be removed.**\n\n2. To add a new expense line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any expense lines, 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 expense line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new expense lines you wish to add.", "example": "456DEF-1234567890" }, "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this bill. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "itemLines": { "description": "The bill's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the bill with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "itemGroupLines": { "description": "The bill's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item group lines for the bill with this array. To keep any existing item group lines, you must include them in this array even if they have not changed. **Any item group lines not included will be removed.**\n\n2. To add a new item group line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item group lines, 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 item group line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item group lines you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this item group 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 }, "itemLines": { "description": "The item group line's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item group line with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing vendor bill while keeping the required references intact. QuickBooks does not let this update request add new purchase order links, and you must continue to supply the vendor, accounts payable account, and at least one expense or item line when you resubmit the bill.\n\n**NOTE:** If you include `expenseLines`, `itemLines`, or `itemGroupLines`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop bills", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a bill. The deletion will fail if the bill is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/build-assemblies": { "get": { "summary": "List QuickBooks Desktop build-assemblies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of build assemblies. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop build-assemblies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inventoryAssemblyItemId": { "description": "The inventory assembly item associated with this build assembly. An inventory assembly item is assembled or manufactured from other inventory items, and the items and/or assemblies that make up the assembly are called components.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this build assembly 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 build assembly is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this build assembly. 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 build assembly. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this build assembly, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this build assembly, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this build assembly, 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": "BUILD-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this build assembly.", "example": "Assembled 25 units of Model ABC-123 Office Chair", "type": "string" }, "quantityToBuild": { "description": "The number of build assembly to be built. The transaction will fail if the number specified here exceeds the number of on-hand components.", "example": 7, "type": "number" }, "markPendingIfRequired": { "description": "When `true`, the build assembly will be marked pending if there are insufficient quantities to complete the build assembly.", "example": true, "type": "boolean" }, "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": [ "inventoryAssemblyItemId", "transactionDate", "quantityToBuild" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a build assembly transaction that consumes component quantities and increases the finished assembly on hand. If components are short you can mark the build as pending instead of failing.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/build-assemblies/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop build-assemblies record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a build assembly by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific build assemblies by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop build-assemblies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the build assembly to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the build assembly to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the build assembly 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" }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this build assembly 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 build assembly is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this build assembly. 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 build assembly. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this build assembly, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "transactionDate": { "description": "The date of this build assembly, 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 build assembly, 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": "BUILD-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this build assembly.", "example": "Assembled 25 units of Model ABC-123 Office Chair", "type": "string" }, "quantityToBuild": { "description": "The number of build assembly to be built. The transaction will fail if the number specified here exceeds the number of on-hand components.", "example": 7, "type": "number" }, "markPendingIfRequired": { "description": "When `true`, the build assembly will be marked pending if there are insufficient quantities to complete the build assembly.", "example": true, "type": "boolean" }, "removePending": { "description": "When `true`, changes this build assembly's status from pending to non-pending, which effectively performs the build transaction. The operation will fail if there are insufficient component quantities on hand to complete the build.", "example": true, "type": "boolean" } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing build assembly.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop build-assemblies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the build assembly to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the build assembly to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a build assembly. The deletion will fail if the build assembly is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/checks": { "get": { "summary": "List QuickBooks Desktop checks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of checks. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop checks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "description": "The bank account from which the funds are being drawn for this check; e.g., Checking or Savings. This check will decrease the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "The person or company who will receive this check.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "refNumber": { "description": "The case-sensitive user-defined reference number for this check, 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\n**IMPORTANT**: For checks, this field is the check number.\n\nMaximum length: 11 characters.", "example": "CHECK-1234", "type": "string", "maxLength": 11 }, "transactionDate": { "type": "string", "format": "date", "description": "The date written on this check, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "memo": { "description": "The memo that is printed on this check.", "example": "Payment for office supplies - Invoice INV-1234", "type": "string" }, "address": { "description": "The address that is printed on the check.", "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 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this check is included in the queue of documents for QuickBooks to print.", "example": true }, "salesTaxCodeId": { "description": "The sales-tax code for this check, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the payee. This can be overridden on the check's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this check'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" }, "applyToTransactions": { "description": "Transactions to be paid by this check. This will create a link between this check and the specified 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 check and check the `linkedTransactions` response field. If fetching a list of checks, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the transaction to be paid by this check.", "example": "123ABC-1234567890" }, "amount": { "description": "The monetary amount from this check to apply to the specified 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": "1000.00", "type": "string" } }, "required": [ "transactionId" ], "additionalProperties": false } }, "expenseLines": { "description": "The check's expense lines, each representing one line in this expense.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the expense 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 } }, "itemLines": { "description": "The check's item lines, each representing the purchase of a specific item or service.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this item 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. If the parent transaction is a bill or an item receipt, you can only link to purchase orders; QuickBooks does not support linking these transactions to other transaction types.\n\nTransaction lines can only be linked when creating this item line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this item 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 item 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 transaction and check the `linkedTransactions` response field. If fetching a list of transactions, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "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 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item 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 } }, "itemGroupLines": { "description": "The check's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this item group 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 group associated with this item group line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item group 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 } } }, "required": [ "itemGroupId" ], "additionalProperties": false } } }, "required": [ "bankAccountId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a non-payroll check from a bank account. QuickBooks uses this request for direct expense disbursements; to pay vendor bills or payroll liabilities you must use the dedicated bill-payment or payroll transactions instead.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/checks/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop checks record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a check by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific checks by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop checks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the check to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the check to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the check 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" }, "bankAccountId": { "description": "The bank account from which the funds are being drawn for this check; e.g., Checking or Savings. This check will decrease the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "The person or company who will receive this check.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "refNumber": { "description": "The case-sensitive user-defined reference number for this check, 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\n**IMPORTANT**: For checks, this field is the check number.\n\nMaximum length: 11 characters.", "example": "CHECK-1234", "type": "string", "maxLength": 11 }, "transactionDate": { "description": "The date written on this check, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "memo": { "description": "The memo that is printed on this check.", "example": "Payment for office supplies - Invoice INV-1234", "type": "string" }, "address": { "description": "The address that is printed on the check.", "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 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this check is included in the queue of documents for QuickBooks to print.", "example": true }, "salesTaxCodeId": { "description": "The sales-tax code for this check, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the payee. This can be overridden on the check's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this check'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" }, "applyToTransactions": { "description": "Transactions to be paid by this check. This will create a link between this check and the specified 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 check and check the `linkedTransactions` response field. If fetching a list of checks, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the transaction to be paid by this check.", "example": "123ABC-1234567890" }, "amount": { "description": "The monetary amount from this check to apply to the specified 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": "1000.00", "type": "string" } }, "required": [ "transactionId" ], "additionalProperties": false } }, "clearExpenseLines": { "description": "When `true`, removes all existing expense lines associated with this check. To modify or add individual expense lines, use the field `expenseLines` instead.", "example": false, "type": "boolean" }, "expenseLines": { "description": "The check's expense lines, each representing one line in this expense.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing expense lines for the check with this array. To keep any existing expense lines, you must include them in this array even if they have not changed. **Any expense lines not included will be removed.**\n\n2. To add a new expense line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any expense lines, 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 expense line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new expense lines you wish to add.", "example": "456DEF-1234567890" }, "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this check. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "itemLines": { "description": "The check's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the check with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "itemGroupLines": { "description": "The check's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item group lines for the check with this array. To keep any existing item group lines, you must include them in this array even if they have not changed. **Any item group lines not included will be removed.**\n\n2. To add a new item group line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item group lines, 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 item group line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item group lines you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this item group 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 }, "itemLines": { "description": "The item group line's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item group line with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a standard check so you can adjust the issuing account, payee details, memo, transaction date, or expense and item lines. This request cannot modify checks created through the bill-payment workflow.\n\n**NOTE:** If you include `expenseLines`, `itemLines`, or `itemGroupLines`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop checks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the check to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the check to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a check. The deletion will fail if the check is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/classes": { "get": { "summary": "List QuickBooks Desktop classes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of classes.\n\n**NOTE:** QuickBooks Desktop does not support pagination for classes; hence, there is no `cursor` parameter. Users typically have few classes.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop classes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this class. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two classes could both have the `name` \"Marketing\", but they could have unique `fullName` values, such as \"Department:Marketing\" and \"Internal:Marketing\".\n\nMaximum length: 31 characters.", "example": "Marketing" }, "isActive": { "description": "Indicates whether this class 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 class one level above this one in the hierarchy. For example, if this class has a `fullName` of \"Department:Marketing\", its parent has a `fullName` of \"Department\". If this class is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "name" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new class.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/classes/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop classes record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a class by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific classes by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop classes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the class to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the class to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the class 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 class. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two classes could both have the `name` \"Marketing\", but they could have unique `fullName` values, such as \"Department:Marketing\" and \"Internal:Marketing\".\n\nMaximum length: 31 characters.", "example": "Marketing", "type": "string", "maxLength": 31 }, "isActive": { "description": "Indicates whether this class is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "parentId": { "description": "The parent class one level above this one in the hierarchy. For example, if this class has a `fullName` of \"Department:Marketing\", its parent has a `fullName` of \"Department\". If this class is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing class.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-charges": { "get": { "summary": "List QuickBooks Desktop credit-card-charges", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of credit card charges. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop credit-card-charges", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "description": "The bank or credit card account to which money is owed for this credit card charge.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "The vendor or company from whom merchandise or services were purchased for this credit card charge.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this credit card charge, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this credit card charge, 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": "CARD-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this credit card charge.", "example": "Office supplies for Q3 marketing campaign", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this credit card charge, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the payee. This can be overridden on the credit card charge's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this credit card charge'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" }, "expenseLines": { "description": "The credit card charge's expense lines, each representing one line in this expense.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the expense 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 } }, "itemLines": { "description": "The credit card charge's item lines, each representing the purchase of a specific item or service.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this item 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. If the parent transaction is a bill or an item receipt, you can only link to purchase orders; QuickBooks does not support linking these transactions to other transaction types.\n\nTransaction lines can only be linked when creating this item line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this item 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 item 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 transaction and check the `linkedTransactions` response field. If fetching a list of transactions, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "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 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item 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 } }, "itemGroupLines": { "description": "The credit card charge's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this item group 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 group associated with this item group line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item group 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 } } }, "required": [ "itemGroupId" ], "additionalProperties": false } } }, "required": [ "accountId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new credit card charge for the specified account.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-charges/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop credit-card-charges record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a credit card charge by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific credit card charges by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop credit-card-charges", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card charge to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card charge to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the credit card charge 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" }, "accountId": { "description": "The bank or credit card account to which money is owed for this credit card charge.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "The vendor or company from whom merchandise or services were purchased for this credit card charge.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this credit card charge, 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 credit card charge, 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": "CARD-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this credit card charge.", "example": "Office supplies for Q3 marketing campaign", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this credit card charge, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the payee. This can be overridden on the credit card charge's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this credit card charge'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" }, "clearExpenseLines": { "description": "When `true`, removes all existing expense lines associated with this credit card charge. To modify or add individual expense lines, use the field `expenseLines` instead.", "example": false, "type": "boolean" }, "expenseLines": { "description": "The credit card charge's expense lines, each representing one line in this expense.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing expense lines for the credit card charge with this array. To keep any existing expense lines, you must include them in this array even if they have not changed. **Any expense lines not included will be removed.**\n\n2. To add a new expense line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any expense lines, 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 expense line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new expense lines you wish to add.", "example": "456DEF-1234567890" }, "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this credit card charge. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "itemLines": { "description": "The credit card charge's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the credit card charge with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "itemGroupLines": { "description": "The credit card charge's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item group lines for the credit card charge with this array. To keep any existing item group lines, you must include them in this array even if they have not changed. **Any item group lines not included will be removed.**\n\n2. To add a new item group line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item group lines, 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 item group line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item group lines you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this item group 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 }, "itemLines": { "description": "The item group line's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item group line with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing credit card charge so you can adjust the credit card account, payee, memo, transaction date, and expense or item lines. The total is recalculated from the line details.\n\n**NOTE:** If you include `expenseLines`, `itemLines`, or `itemGroupLines`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop credit-card-charges", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card charge to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card charge to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a credit card charge. The deletion will fail if the credit card charge is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-credits": { "get": { "summary": "List QuickBooks Desktop credit-card-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of credit card credits. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop credit-card-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "description": "The bank or credit card account to which this credit card credit is posted.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "The vendor or company from whom this credit card credit was received for purchased merchandise or services.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this credit card credit, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this credit card credit, 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": "CREDIT-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this credit card credit.", "example": "Refund for returned office supplies", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this credit card credit, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the payee. This can be overridden on the credit card credit's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this credit card credit'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" }, "expenseLines": { "description": "The credit card credit's expense lines, each representing one line in this expense.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the expense 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 } }, "itemLines": { "description": "The credit card credit's item lines, each representing the purchase of a specific item or service.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this item 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. If the parent transaction is a bill or an item receipt, you can only link to purchase orders; QuickBooks does not support linking these transactions to other transaction types.\n\nTransaction lines can only be linked when creating this item line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this item 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 item 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 transaction and check the `linkedTransactions` response field. If fetching a list of transactions, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "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 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item 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 } }, "itemGroupLines": { "description": "The credit card credit's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this item group 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 group associated with this item group line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item group 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 } } }, "required": [ "itemGroupId" ], "additionalProperties": false } } }, "required": [ "accountId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new credit card credit for the specified account.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-credits/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop credit-card-credits record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a credit card credit by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific credit card credits by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop credit-card-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card credit to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card credit to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the credit card credit 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" }, "accountId": { "description": "The bank or credit card account to which this credit card credit is posted.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "The vendor or company from whom this credit card credit was received for purchased merchandise or services.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this credit card credit, 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 credit card credit, 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": "CREDIT-1234", "type": "string", "maxLength": 11 }, "memo": { "description": "A memo or note for this credit card credit.", "example": "Refund for returned office supplies", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this credit card credit, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the payee. This can be overridden on the credit card credit's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this credit card credit'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" }, "clearExpenseLines": { "description": "When `true`, removes all existing expense lines associated with this credit card credit. To modify or add individual expense lines, use the field `expenseLines` instead.", "example": false, "type": "boolean" }, "expenseLines": { "description": "The credit card credit's expense lines, each representing one line in this expense.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing expense lines for the credit card credit with this array. To keep any existing expense lines, you must include them in this array even if they have not changed. **Any expense lines not included will be removed.**\n\n2. To add a new expense line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any expense lines, 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 expense line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new expense lines you wish to add.", "example": "456DEF-1234567890" }, "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this credit card credit. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "itemLines": { "description": "The credit card credit's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the credit card credit with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "itemGroupLines": { "description": "The credit card credit's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item group lines for the credit card credit with this array. To keep any existing item group lines, you must include them in this array even if they have not changed. **Any item group lines not included will be removed.**\n\n2. To add a new item group line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item group lines, 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 item group line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item group lines you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this item group 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 }, "itemLines": { "description": "The item group line's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item group line with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing credit card credit.\n\n**NOTE:** If you include `expenseLines`, `itemLines`, or `itemGroupLines`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop credit-card-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card credit to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card credit to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a credit card credit. The deletion will fail if the credit card credit is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-refunds": { "get": { "summary": "List QuickBooks Desktop credit-card-refunds", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of credit card refunds. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop credit-card-refunds", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this credit card refund.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "refundFromAccountId": { "description": "The account providing funds for this credit card refund. This is typically the Undeposited Funds account used to hold customer payments. If omitted, QuickBooks Desktop uses the default Undeposited Funds account configured in the company file.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "receivablesAccountId": { "description": "The Accounts-Receivable (A/R) account to which this credit card refund 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 credit card refund is linked to other transactions, this A/R account must match the `receivablesAccount` used in all linked transactions. For example, when refunding a credit card payment, the A/R account must match the one used in each linked credit transaction being refunded.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this credit card refund, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this credit card refund, 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": "REFUND-1234", "type": "string", "maxLength": 11 }, "address": { "description": "The address that is printed on the credit card refund.", "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 }, "paymentMethodId": { "description": "The credit card refund's payment method (e.g., cash, check, credit card).\n\n**NOTE**: If this credit card refund contains credit card transaction data supplied from QuickBooks Merchant Services (QBMS) transaction responses, you must specify a credit card payment method (e.g., \"Visa\", \"MasterCard\", etc.).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this credit card refund.", "example": "Refund to customer for duplicate credit card charge", "type": "string" }, "creditCardTransaction": { "description": "The credit card transaction data for this credit card refund's payment when using QuickBooks Merchant Services (QBMS). If specifying this field, you must also specify the `paymentMethod` field.", "type": "object", "properties": { "request": { "description": "The transaction request data originally supplied for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "number": { "type": "string", "description": "The credit card number. Must be masked with lower case \"x\" and no dashes.", "example": "xxxxxxxxxxxx1234" }, "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": { "type": "string", "description": "The cardholder's name on the card.", "example": "John Doe" }, "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" }, "commercialCardCode": { "description": "The commercial card code identifies the type of business credit card being used (purchase, corporate, or business) for Visa and Mastercard transactions only. When provided, this code may qualify the transaction for lower processing fees compared to the standard rates that apply when no code is specified.", "example": "corporate", "type": "string" }, "transactionMode": { "description": "Indicates whether this credit card transaction came from a card swipe (`card_present`) or not (`card_not_present`).", "example": "card_not_present", "type": "string", "enum": [ "card_not_present", "card_present" ], "default": "card_not_present" }, "transactionType": { "description": "The QBMS transaction type from which the current transaction data originated.", "example": "charge", "type": "string", "enum": [ "authorization", "capture", "charge", "refund", "voice_authorization" ] } }, "required": [ "number", "expirationMonth", "expirationYear", "name" ], "additionalProperties": false }, "response": { "description": "The transaction response data for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "statusCode": { "description": "The status code returned in the original QBMS transaction response for this credit card transaction.", "example": 0, "type": "number" }, "statusMessage": { "type": "string", "description": "The status message returned in the original QBMS transaction response for this credit card transaction.", "example": "Success" }, "creditCardTransactionId": { "type": "string", "description": "The ID returned from the credit card processor for this credit card transaction.", "example": "1234567890" }, "merchantAccountNumber": { "type": "string", "description": "The QBMS account number of the merchant who is running this transaction using the customer's credit card.", "example": "1234567890" }, "authorizationCode": { "description": "The authorization code returned from the credit card processor to indicate that this charge will be paid by the card issuer.", "example": "1234567890", "type": "string" }, "avsStreetStatus": { "description": "Indicates whether the street address supplied in the transaction request matches the customer's address on file at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "avsZipStatus": { "description": "Indicates whether the customer postal ZIP code supplied in the transaction request matches the customer's postal code recognized at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "cardSecurityCodeMatch": { "description": "Indicates whether the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "reconBatchId": { "description": "An internal ID returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": "1234567890", "type": "string" }, "paymentGroupingCode": { "description": "An internal code returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "paymentStatus": { "description": "Indicates whether this credit card transaction is known to have been successfully processed by the card issuer.", "example": "completed", "type": "string", "enum": [ "completed", "unknown" ] }, "transactionAuthorizedAt": { "type": "string", "description": "The date and time when the credit card processor authorized this credit card transaction.", "example": "2024-01-01 12:34:56 UTC" }, "transactionAuthorizationStamp": { "description": "An internal value for this credit card transaction, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "clientTransactionId": { "description": "A value returned from QBMS transactions for future use by the QuickBooks Reconciliation feature.", "example": "1234567890", "type": "string" } }, "required": [ "statusCode", "statusMessage", "creditCardTransactionId", "merchantAccountNumber", "paymentStatus", "transactionAuthorizedAt" ], "additionalProperties": false } }, "additionalProperties": false }, "exchangeRate": { "description": "The market exchange rate between this credit card refund'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" }, "refundAppliedToTransactions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the credit transaction being refunded by this credit card refund.", "example": "123ABC-1234567890" }, "refundAmount": { "type": "string", "description": "The monetary amount to refund from the linked credit transaction within this credit 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": "15.00" } }, "required": [ "transactionId", "refundAmount" ], "additionalProperties": false }, "description": "The credit transactions to refund in this credit card refund. Each entry links this credit card refund to an existing credit (for example, a credit memo or unused receive-payment credit).\n\n**IMPORTANT**: The `refundAmount` for each linked credit cannot exceed that credit's remaining balance, and the combined `refundAmount` across all links cannot exceed this credit card refund's `totalAmount`." } }, "required": [ "customerId", "transactionDate", "refundAppliedToTransactions" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a credit card refund linked to one or more existing credit transactions, such as credit memos or overpayments. You must supply at least one entry in `refundAppliedToTransactions`, and the refund amount cannot exceed the available balance on the linked credits.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-refunds/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop credit-card-refunds record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a credit card refund by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific credit card refunds by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "delete": { "summary": "Delete QuickBooks Desktop credit-card-refunds", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card refund to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card refund to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a credit card refund. The deletion will fail if the credit card refund is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-memos": { "get": { "summary": "List QuickBooks Desktop credit-memos", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of credit memos. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop credit-memos", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this credit memo.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The credit memo'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 credit memo'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 credit memo 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 credit memo 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 credit memo when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this credit memo, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this credit memo, 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": "CM-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The credit memo'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 credit memo'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 credit memo has not been completed.", "example": false, "type": "boolean" }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this credit memo. This field is often used to cross-reference the credit memo with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The credit memo'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 credit memo must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The credit memo'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 credit memo 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 credit memo 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 credit memo, 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 credit memo'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 credit memo that appears in the account register and customer register, but not on the credit memo itself.", "example": "Customer refund for damaged shipment", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the credit memo.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this credit memo is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this credit memo 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 credit memo, 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 credit memo. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memos 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 credit memo'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 credit memo's line items, each representing a single product or service sold.\n\n**IMPORTANT**: You must specify `lines`, `lineGroups`, or both when creating a credit memo.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this credit memo 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": 36 }, "description": { "description": "A description of this credit memo line.", "example": "Return of defective product - Widget Model X123", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line. This overrides any price level set on the corresponding customer. The resulting credit memo line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The credit memo 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 credit memo lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this credit memo 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" }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this credit memo 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 credit memo line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memo 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 credit memo line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memo 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 credit memo 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 credit memo'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 credit memo.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The credit memo 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": 36 }, "quantity": { "description": "The quantity of the item group associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the credit memo 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 } } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new credit memo.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-memos/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop credit-memos record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a credit memo by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific credit memos by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop credit-memos", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit memo to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit memo to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the credit memo 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 credit memo.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The credit memo'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 credit memo'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 credit memo 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 credit memo 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 credit memo when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this credit memo, 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 credit memo, 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": "CM-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The credit memo'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 credit memo'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 credit memo has not been completed.", "example": false, "type": "boolean" }, "purchaseOrderNumber": { "description": "The customer's Purchase Order (PO) number associated with this credit memo. This field is often used to cross-reference the credit memo with the customer's purchasing system.\n\nMaximum length: 25 characters.", "example": "PO-1234", "type": "string", "maxLength": 25 }, "termsId": { "description": "The credit memo'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 credit memo must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The credit memo'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 credit memo 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 credit memo 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 credit memo, 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 credit memo'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 credit memo that appears in the account register and customer register, but not on the credit memo itself.", "example": "Customer refund for damaged shipment", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the credit memo.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this credit memo is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this credit memo 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 credit memo, 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 credit memo. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memos 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 credit memo'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 credit memo'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 credit memo 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 credit memo line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new credit memo lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this credit memo 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": 36 }, "description": { "description": "A description of this credit memo line.", "example": "Return of defective product - Widget Model X123", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line. This overrides any price level set on the corresponding customer. The resulting credit memo line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The credit memo 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 credit memo lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this credit memo 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" }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this credit memo 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 credit memo line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memo 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 credit memo line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memo 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 credit memo'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 credit memo 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 credit memo line group you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new credit memo line groups you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The credit memo 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": 36 }, "quantity": { "description": "The quantity of the item group associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new credit memo lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this credit memo 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": 36 }, "description": { "description": "A description of this credit memo line.", "example": "Return of defective product - Widget Model X123", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line. This overrides any price level set on the corresponding customer. The resulting credit memo line will not show this price level, only the final `rate` calculated from it.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The credit memo 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 credit memo lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this credit memo 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" }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this credit memo 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 credit memo line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo 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 credit memo line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memo 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 credit memo line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all credit memo 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 } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing credit memo.\n\n**NOTE:** If you include `lines` or `lineGroups`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop credit-memos", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit memo to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit memo to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a credit memo. The deletion will fail if the credit memo is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/currencies": { "get": { "summary": "List QuickBooks Desktop currencies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of currencies.\n\n**NOTE:** QuickBooks Desktop does not support pagination for currencies; hence, there is no `cursor` parameter. Users typically have few currencies.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop currencies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 64, "description": "The case-insensitive unique name of this currency, unique across all currencies. For built-in currencies, the name is the internationally accepted currency name and is not editable.\n\n**NOTE**: Currencies 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: 64 characters.", "example": "United States Dollar" }, "isActive": { "description": "Indicates whether this currency is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "currencyCode": { "type": "string", "maxLength": 3, "description": "The internationally accepted currency code used by this currency, typically based on the ISO 4217 standard (for example, USD for US Dollars). Built-in QuickBooks currencies follow ISO 4217. For user-defined currencies, following ISO 4217 is recommended but not required. In many cases, the three-letter code is formed from the country's two-letter internet code plus a currency letter (e.g., BZ + D → BZD for Belize Dollar).\n\nMaximum length: 3 characters.", "example": "USD" }, "currencyFormat": { "description": "Controls how this currency displays thousands separators, grouping, and decimal places.", "type": "object", "properties": { "thousandSeparator": { "description": "Controls the thousands separator when displaying currency values (for example, \"1,000,000\"). Defaults to comma.", "example": "comma", "type": "string", "enum": [ "apostrophe", "comma", "period", "space" ], "default": "comma" }, "thousandSeparatorGrouping": { "description": "Controls how digits are grouped for thousands when displaying currency values (for example, \"10,000,000\").", "example": "xx_xxx_xxx", "type": "string", "enum": [ "x_xx_xx_xxx", "xx_xxx_xxx" ], "default": "xx_xxx_xxx" }, "decimalPlaces": { "description": "Controls the number of decimal places displayed for currency values. Use `0` to hide decimals or `2` to display cents.", "example": "2", "type": "string", "enum": [ "0", "2" ], "default": "2" }, "decimalSeparator": { "description": "Controls the decimal separator when displaying currency values (for example, \"1.00\" vs \"1,00\"). Defaults to period.", "example": "period", "type": "string", "enum": [ "comma", "period" ], "default": "period" } }, "additionalProperties": false } }, "required": [ "name", "currencyCode" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a user-defined currency with the specified name and currency code. Exchange rates for user-defined currencies are not updated automatically by QuickBooks Desktop; update them manually as needed.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/currencies/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop currencies record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a currency by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific currencies by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop currencies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the currency to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the currency to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the currency 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 currency, unique across all currencies. For built-in currencies, the name is the internationally accepted currency name and is not editable.\n\n**NOTE**: Currencies 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: 64 characters.", "example": "United States Dollar", "type": "string", "maxLength": 64 }, "isActive": { "description": "Indicates whether this currency is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "currencyCode": { "description": "The internationally accepted currency code used by this currency, typically based on the ISO 4217 standard (for example, USD for US Dollars). Built-in QuickBooks currencies follow ISO 4217. For user-defined currencies, following ISO 4217 is recommended but not required. In many cases, the three-letter code is formed from the country's two-letter internet code plus a currency letter (e.g., BZ + D → BZD for Belize Dollar).\n\nMaximum length: 3 characters.", "example": "USD", "type": "string", "maxLength": 3 }, "currencyFormat": { "description": "Controls how this currency displays thousands separators, grouping, and decimal places.", "type": "object", "properties": { "thousandSeparator": { "description": "Controls the thousands separator when displaying currency values (for example, \"1,000,000\"). Defaults to comma.", "example": "comma", "type": "string", "enum": [ "apostrophe", "comma", "period", "space" ] }, "thousandSeparatorGrouping": { "description": "Controls how digits are grouped for thousands when displaying currency values (for example, \"10,000,000\").", "example": "xx_xxx_xxx", "type": "string", "enum": [ "x_xx_xx_xxx", "xx_xxx_xxx" ] }, "decimalPlaces": { "description": "Controls the number of decimal places displayed for currency values. Use `0` to hide decimals or `2` to display cents.", "example": "2", "type": "string", "enum": [ "0", "2" ] }, "decimalSeparator": { "description": "Controls the decimal separator when displaying currency values (for example, \"1.00\" vs \"1,00\"). Defaults to period.", "example": "period", "type": "string", "enum": [ "comma", "period" ] } }, "additionalProperties": false } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing currency. For built-in currencies, only the `isActive` status can be changed; name and currency code are not editable. For user-defined currencies, all fields in this request are editable.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/customer-types": { "get": { "summary": "List QuickBooks Desktop customer-types", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of customer types.\n\n**NOTE:** QuickBooks Desktop does not support pagination for customer types; hence, there is no `cursor` parameter. Users typically have few customer types.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop customer-types", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this customer type. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two customer types could both have the `name` \"Healthcare\", but they could have unique `fullName` values, such as \"Industry:Healthcare\" and \"Region:Healthcare\".\n\nMaximum length: 31 characters.", "example": "Healthcare" }, "isActive": { "description": "Indicates whether this customer type 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 customer type one level above this one in the hierarchy. For example, if this customer type has a `fullName` of \"Industry:Healthcare\", its parent has a `fullName` of \"Industry\". If this customer type is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "name" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new customer type.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/customer-types/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop customer-types record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a customer type by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific customer types by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/date-driven-terms": { "get": { "summary": "List QuickBooks Desktop date-driven-terms", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of date-driven terms.\n\n**NOTE:** QuickBooks Desktop does not support pagination for date-driven terms; hence, there is no `cursor` parameter. Users typically have few date-driven terms.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop date-driven-terms", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this date-driven term, unique across all date-driven terms.\n\n**NOTE**: Date-driven terms 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": "2% 5th Net 25th" }, "isActive": { "description": "Indicates whether this date-driven term is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "dueDayOfMonth": { "description": "The day of the month when full payment is due without discount.", "example": 15, "type": "number" }, "gracePeriodDays": { "description": "The number of days before `dueDayOfMonth` when an invoice or bill issued within this threshold is considered due the following month. For example, with `dueDayOfMonth` set to 15 and `gracePeriodDays` set to 2, an invoice issued on the 13th would be due on the 15th of the next month, while an invoice issued on the 12th would be due on the 15th of the current month.", "example": 2, "type": "number" }, "discountDayOfMonth": { "description": "The day of the month within which payment must be received to qualify for the discount specified by `discountPercentage`.", "example": 5, "type": "number" }, "discountPercentage": { "description": "The discount percentage applied to the payment if received on or before the specified `discountDayOfMonth`. The value is between 0 and 100.", "example": "10", "type": "string" } }, "required": [ "name", "dueDayOfMonth" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a date-driven term that sets the payment due on a specific day of the month and can optionally grant an early-payment discount before `discountDayOfMonth`. Use it when you need due dates tied to calendar days instead of a fixed number of days after the transaction.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/date-driven-terms/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop date-driven-terms record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a date-driven term by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific date-driven terms by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/deleted-list-objects": { "get": { "summary": "List QuickBooks Desktop deleted-list-objects", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists deleted non-transaction list-objects (e.g., customers, vendors, employees, items) from the last 90 days. Results are grouped by list-object type and ordered by actual delete time (ascending). For deleted transactions (e.g., invoices, bills, estimates), see the deleted-transactions endpoint.\n\n**NOTE:** QuickBooks Desktop does not support pagination for deleted list-objects; hence, there is no `cursor` parameter. Users typically have few deleted list-objects.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/deleted-transactions": { "get": { "summary": "List QuickBooks Desktop deleted-transactions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists deleted transactions of the specified type(s) (e.g., invoice, bill, estimate) in the last 90 days. Results are grouped by transaction type and ordered by actual delete time (ascending). NOTE: For deleted non-transaction list-objects (e.g., customer, vendor, employee), see the deleted-list-objects endpoint.\n\n**NOTE:** QuickBooks Desktop does not support pagination for deleted transactions; hence, there is no `cursor` parameter. Users typically have few deleted transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/deposits": { "get": { "summary": "List QuickBooks Desktop deposits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of deposits. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop deposits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionDate": { "type": "string", "format": "date", "description": "The date of this deposit, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "depositToAccountId": { "description": "The account where the funds for this deposit will be deposited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this deposit.", "example": "Batch settlement deposit", "type": "string" }, "cashBack": { "description": "Cash back taken out of this deposit and recorded to another account, such as Petty Cash.", "type": "object", "properties": { "accountId": { "description": "The account where this deposit cash-back line's cash-back amount is recorded, such as Petty Cash. This amount reduces the total credited to the deposit's destination account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this deposit cash-back line.", "example": "Cash back from deposit", "type": "string" }, "amount": { "description": "The cash-back amount taken out of the deposit and recorded to this deposit cash-back line's account, 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": "1000.00", "type": "string" } }, "required": [ "accountId" ], "additionalProperties": false }, "currencyId": { "description": "The deposit'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 }, "exchangeRate": { "description": "The market exchange rate between this deposit'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 deposit's deposit lines, each representing either an existing payment selected for deposit or a manual transfer from another account into the deposit account.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "paymentTransactionId": { "description": "The ID of an existing undeposited payment to include in this deposit line. Use the `paymentTransactionId` from a payments-to-deposit result, or the `id` from the original receive-payment response. If the source payment has multiple depositable lines and you omit `paymentTransactionLineId`, QuickBooks Desktop deposits only the first line.", "example": "123ABC-1234567890", "type": "string", "maxLength": 36 }, "paymentTransactionLineId": { "type": "string", "maxLength": 36, "description": "The line ID for the specific undeposited payment line to include in this deposit line. Use the `paymentTransactionLineId` from a payments-to-deposit result. If the source payment has multiple depositable lines, provide this field with `paymentTransactionId` to choose the exact line.", "example": "456DEF-1234567890" }, "overrideMemo": { "description": "The memo to use for this deposit line, overriding the memo from the existing payment line.\n\nMaximum length: 4095 characters.", "example": "Batch settlement deposit", "type": "string", "maxLength": 4095 }, "overrideCheckNumber": { "description": "The check number to use for this deposit line, overriding the check number from the existing payment line.\n\nMaximum length: 11 characters.", "example": "1234567890", "type": "string", "maxLength": 11 }, "overrideClassId": { "description": "The class to use for this deposit line, overriding the class from the existing payment line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "entityId": { "description": "The customer, vendor, employee, or person on QuickBooks's \"Other Names\" list associated with this manual deposit line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "accountId": { "description": "For a manual deposit line, the account that the funds are transferred from into the deposit's destination account. To deposit an existing payment instead, use `paymentTransactionId` and, when needed, `paymentTransactionLineId`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this deposit line.", "example": "Payment batched into settlement deposit", "type": "string" }, "checkNumber": { "description": "The check number of a check received for this deposit line.", "example": "1234567890", "type": "string" }, "paymentMethodId": { "description": "The deposit line's payment method (e.g., cash, check, credit card).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The deposit 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.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "For a manual deposit line, the amount transferred from the line's account into the deposit's destination account, 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": "1000.00", "type": "string" } }, "additionalProperties": false } } }, "required": [ "transactionDate", "depositToAccountId" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a deposit into a QuickBooks Desktop bank or other asset account. Lines can either reference existing payments waiting to be deposited, using `paymentTransactionId` and optionally `paymentTransactionLineId`, or describe a manual transfer from another account using `accountId` and related line details.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/deposits/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop deposits record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a deposit by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific deposits by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop deposits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the deposit to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the deposit to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the deposit 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" }, "transactionDate": { "description": "The date of this deposit, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "depositToAccountId": { "description": "The account where the funds for this deposit will be deposited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this deposit.", "example": "Batch settlement deposit", "type": "string" }, "cashBack": { "description": "Cash back taken out of this deposit and recorded to another account, such as Petty Cash.", "type": "object", "properties": { "accountId": { "description": "The account where this deposit cash-back line's cash-back amount is recorded, such as Petty Cash. This amount reduces the total credited to the deposit's destination account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this deposit cash-back line.", "example": "Cash back from deposit", "type": "string" }, "amount": { "description": "The cash-back amount taken out of the deposit and recorded to this deposit cash-back line's account, 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": "1000.00", "type": "string" } }, "additionalProperties": false }, "currencyId": { "description": "The deposit'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 }, "exchangeRate": { "description": "The market exchange rate between this deposit'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 deposit's deposit lines, each representing either an existing payment selected for deposit or a manual transfer from another account into the deposit account.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing deposit lines for the deposit with this array. To keep any existing deposit lines, you must include them in this array even if they have not changed. **Any deposit lines not included will be removed.**\n\n2. To add a new deposit line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any deposit lines, 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 deposit line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new deposit lines you wish to add.", "example": "456DEF-1234567890" }, "paymentTransactionId": { "description": "The ID of an existing undeposited payment to include in this deposit line. Use the `paymentTransactionId` from a payments-to-deposit result, or the `id` from the original receive-payment response. If the source payment has multiple depositable lines and you omit `paymentTransactionLineId`, QuickBooks Desktop deposits only the first line.", "example": "123ABC-1234567890", "type": "string", "maxLength": 36 }, "paymentTransactionLineId": { "type": "string", "maxLength": 36, "description": "The line ID for the specific undeposited payment line to include in this deposit line. Use the `paymentTransactionLineId` from a payments-to-deposit result. If the source payment has multiple depositable lines, provide this field with `paymentTransactionId` to choose the exact line.", "example": "456DEF-1234567890" }, "overrideMemo": { "description": "The memo to use for this deposit line, overriding the memo from the existing payment line.\n\nMaximum length: 4095 characters.", "example": "Batch settlement deposit", "type": "string", "maxLength": 4095 }, "overrideCheckNumber": { "description": "The check number to use for this deposit line, overriding the check number from the existing payment line.\n\nMaximum length: 11 characters.", "example": "1234567890", "type": "string", "maxLength": 11 }, "overrideClassId": { "description": "The class to use for this deposit line, overriding the class from the existing payment line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "entityId": { "description": "The customer, vendor, employee, or person on QuickBooks's \"Other Names\" list associated with this manual deposit line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "accountId": { "description": "For a manual deposit line, the account that the funds are transferred from into the deposit's destination account. To deposit an existing payment instead, use `paymentTransactionId` and, when needed, `paymentTransactionLineId`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this deposit line.", "example": "Payment batched into settlement deposit", "type": "string" }, "checkNumber": { "description": "The check number of a check received for this deposit line.", "example": "1234567890", "type": "string" }, "paymentMethodId": { "description": "The deposit line's payment method (e.g., cash, check, credit card).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The deposit 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.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "For a manual deposit line, the amount transferred from the line's account into the deposit's destination account, 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": "1000.00", "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing deposit.\n\n**NOTE:** If you include `lines`, QuickBooks Desktop replaces that line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop deposits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the deposit to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the deposit to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a deposit. The deletion will fail if the deposit is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/discount-items": { "get": { "summary": "List QuickBooks Desktop discount-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of discount items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop discount-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive name of this discount item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two discount items could both have the `name` \"10% labor discount\", but they could have unique `fullName` values, such as \"Discounts:10% labor discount\" and \"Promotions:10% labor discount\".\n\nMaximum length: 31 characters.", "example": "10% labor discount" }, "barcode": { "description": "The discount 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 discount 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 discount 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 discount item one level above this one in the hierarchy. For example, if this discount item has a `fullName` of \"Discounts:10% labor discount\", its parent has a `fullName` of \"Discounts\". If this discount item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "description": { "description": "The discount item's description that will appear on sales forms that include this item.", "example": "10% discount for early payment on labor charges", "type": "string" }, "salesTaxCodeId": { "description": "The default sales-tax code for this discount 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 }, "discountRate": { "description": "The monetary amount to subtract from the total or subtotal when applying this discount item to a transaction, represented as a decimal string.\n\n**NOTE**: A flat rate discount applies to ALL lines recorded above it and distributes the discount amount equally across those lines, which affects tax calculations. For example, a $10 discount applied to a $100 taxable item and $100 non-taxable item would result in a $5 taxable discount and $5 non-taxable discount.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "25.00", "type": "string" }, "discountRatePercent": { "description": "The percentage amount to subtract from the total or subtotal when applying this discount item to a transaction.\n\n**NOTE**: A percentage discount only applies to the line immediately above it, so tax implications only affect that specific line.", "example": "10.5", "type": "string" }, "accountId": { "description": "The posting account to which transactions involving this discount item are posted for tracking discounts.", "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" } }, "required": [ "name", "accountId" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a discount item that subtracts either a percentage or fixed amount from transaction totals. Percentage discounts only affect the preceding line, while fixed-amount discounts reduce the accumulated amount above them unless you bound the target lines with a subtotal item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/discount-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop discount-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a discount item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific discount items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop discount-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the discount item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the discount item to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the discount 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 discount item. Not guaranteed to be unique because it does not include the names of its hierarchical parent objects like `fullName` does. For example, two discount items could both have the `name` \"10% labor discount\", but they could have unique `fullName` values, such as \"Discounts:10% labor discount\" and \"Promotions:10% labor discount\".\n\nMaximum length: 31 characters.", "example": "10% labor discount", "type": "string", "maxLength": 31 }, "barcode": { "description": "The discount 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 discount item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The discount 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 discount item one level above this one in the hierarchy. For example, if this discount item has a `fullName` of \"Discounts:10% labor discount\", its parent has a `fullName` of \"Discounts\". If this discount item is at the top level, this field will be `null`.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "description": { "description": "The discount item's description that will appear on sales forms that include this item.", "example": "10% discount for early payment on labor charges", "type": "string" }, "salesTaxCodeId": { "description": "The default sales-tax code for this discount 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 }, "discountRate": { "description": "The monetary amount to subtract from the total or subtotal when applying this discount item to a transaction, represented as a decimal string.\n\n**NOTE**: A flat rate discount applies to ALL lines recorded above it and distributes the discount amount equally across those lines, which affects tax calculations. For example, a $10 discount applied to a $100 taxable item and $100 non-taxable item would result in a $5 taxable discount and $5 non-taxable discount.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "25.00", "type": "string" }, "discountRatePercent": { "description": "The percentage amount to subtract from the total or subtotal when applying this discount item to a transaction.\n\n**NOTE**: A percentage discount only applies to the line immediately above it, so tax implications only affect that specific line.", "example": "10.5", "type": "string" }, "accountId": { "description": "The posting account to which transactions involving this discount item are posted for tracking discounts.", "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 discount 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" } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a discount item, including its linked account or discount rate. When changing the account, use `updateExistingTransactionsAccount` to control whether existing transactions that reference the item should also be updated.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/employees": { "get": { "summary": "List QuickBooks Desktop employees", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of employees.\n\n**NOTE:** QuickBooks Desktop does not support pagination for employees; hence, there is no `cursor` parameter. Users typically have few employees.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop employees", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "description": "Indicates whether this employee is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "salutation": { "description": "The employee's formal salutation title that precedes their name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The employee's first name.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The employee's middle name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The employee's last name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The employee's job title.", "example": "Purchasing Manager", "type": "string" }, "supervisorId": { "description": "The employee's supervisor. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "department": { "description": "The employee's department. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "Sales", "type": "string" }, "description": { "description": "A description of this employee. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "This employee is a key employee.", "type": "string" }, "targetBonus": { "description": "The target bonus for this employee, represented as a decimal string. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "10000.00", "type": "string" }, "address": { "description": "The employee's address.\n\nIf the company uses QuickBooks Payroll for this employee, this address must specify a complete address, including city, state, ZIP (or postal) code, and at least one line of the street address.", "type": "object", "properties": { "line1": { "description": "The first line of the employee 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 employee 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 employee address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the employee 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 employee address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The U.S. state of the employee address. QuickBooks requires this field to be a U.S. state abbreviation (e.g., \"CA\" for California). See enum for all possible values.", "example": "CA", "type": "string", "enum": [ "none", "armed_forces_americas", "armed_forces_europe", "armed_forces_pacific", "AK", "AL", "AR", "AZ", "CA", "CO", "CT", "DC", "DE", "FL", "GA", "HI", "IA", "ID", "IL", "IN", "KS", "KY", "LA", "MA", "MD", "ME", "MI", "MN", "MO", "MS", "MT", "NB", "NC", "ND", "NE", "NH", "NJ", "NM", "NV", "NY", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VA", "VT", "WA", "WI", "WV", "WY" ] }, "postalCode": { "description": "The postal code or ZIP code of the employee address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the employee address.", "example": "United States", "type": "string" } }, "additionalProperties": false }, "printAs": { "description": "The name to use when printing this employee from QuickBooks. By default, this is the same as the `name` field.", "example": "John Doe", "type": "string" }, "phone": { "description": "The employee's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "mobile": { "description": "The employee's mobile phone number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "pager": { "description": "The employee's pager number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "pagerPin": { "description": "The employee's pager PIN.", "example": "1234", "type": "string" }, "alternatePhone": { "description": "The employee's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The employee's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "ssn": { "description": "The employee's Social Security Number. The value can be with or without dashes.\n\n**NOTE**: This field cannot be changed after the employee is created.", "example": "123-45-6789", "type": "string" }, "email": { "description": "The employee's email address.", "example": "employee@example.com", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this employee, 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 } }, "emergencyContact": { "description": "The employee's emergency contacts.", "type": "object", "properties": { "primaryContact": { "description": "The employee's primary emergency contact.", "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" }, "relation": { "description": "The relationship of the employee to the employee.", "example": "spouse", "type": "string", "enum": [ "brother", "daughter", "father", "friend", "mother", "other", "partner", "sister", "son", "spouse" ] } }, "required": [ "name", "value" ], "additionalProperties": false }, "secondaryContact": { "description": "The employee's secondary emergency contact.", "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" }, "relation": { "description": "The relationship of the employee to the employee.", "example": "spouse", "type": "string", "enum": [ "brother", "daughter", "father", "friend", "mother", "other", "partner", "sister", "son", "spouse" ] } }, "required": [ "name", "value" ], "additionalProperties": false } }, "additionalProperties": false }, "employeeType": { "description": "The employee type. This affects payroll taxes - a statutory employee is defined as an employee by statute. Note that owners/partners are typically on the \"Other Names\" list in QuickBooks, but if listed as an employee their type will be `owner`.", "example": "regular", "type": "string", "enum": [ "officer", "owner", "regular", "statutory" ], "default": "regular" }, "employmentStatus": { "description": "Indicates whether this employee is a part-time or full-time employee.", "example": "full_time", "type": "string", "enum": [ "full_time", "part_time" ] }, "overtimeExemptStatus": { "description": "Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA).\n", "example": "exempt", "type": "string", "enum": [ "exempt", "non_exempt" ] }, "keyEmployeeStatus": { "description": "Indicates whether this employee is a key employee.", "example": "key_employee", "type": "string", "enum": [ "key_employee", "non_key_employee" ] }, "gender": { "description": "This employee's gender.", "example": "male", "type": "string", "enum": [ "male", "female" ] }, "hiredDate": { "description": "The date this employee was hired, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "originalHireDate": { "description": "The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "adjustedServiceDate": { "description": "The adjusted service date for this employee, in ISO 8601 format (YYYY-MM-DD). This date accounts for previous employment periods or leaves that affect seniority.", "example": "2024-01-01", "type": "string", "format": "date" }, "terminationDate": { "description": "The date this employee's employment ended with the company, in ISO 8601 format (YYYY-MM-DD). This is also known as the released date or separation date.", "example": "2024-01-01", "type": "string", "format": "date" }, "birthDate": { "description": "This employee's date of birth, in ISO 8601 format (YYYY-MM-DD).", "example": "1990-01-01", "type": "string", "format": "date" }, "usCitizenshipStatus": { "description": "Indicates whether this employee is a U.S. citizen.", "example": "citizen", "type": "string", "enum": [ "citizen", "non_citizen" ] }, "ethnicity": { "description": "This employee's ethnicity.", "example": "asian", "type": "string", "enum": [ "american_indian", "asian", "black", "hawaiian", "hispanic", "white", "two_or_more_races" ] }, "disabilityStatus": { "description": "Indicates whether this employee is disabled.", "example": "disabled", "type": "string", "enum": [ "disabled", "non_disabled" ] }, "disabilityDescription": { "description": "A description of this employee's disability.", "example": "Cerebral Palsy", "type": "string" }, "i9OnFileStatus": { "description": "Indicates whether this employee's I-9 is on file.", "example": "on_file", "type": "string", "enum": [ "on_file", "not_on_file" ] }, "workAuthorizationExpirationDate": { "description": "The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "usVeteranStatus": { "description": "Indicates whether this employee is a U.S. veteran.", "example": "veteran", "type": "string", "enum": [ "veteran", "non_veteran" ] }, "militaryStatus": { "description": "This employee's military status if they are a U.S. veteran.", "example": "active", "type": "string", "enum": [ "active", "reserve" ] }, "accountNumber": { "description": "The employee'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 employee.", "example": "This employee is a key employee.", "type": "string" }, "additionalNotes": { "description": "Additional notes about this employee.", "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 } }, "billingRateId": { "description": "The employee's billing rate, used to override service item rates in time tracking activities.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "employeePayroll": { "description": "The employee's payroll information.", "type": "object", "properties": { "payPeriod": { "description": "How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks.", "example": "weekly", "type": "string", "enum": [ "biweekly", "daily", "monthly", "quarterly", "semimonthly", "weekly", "yearly" ] }, "classId": { "description": "The employee'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 }, "earnings": { "description": "The employee's earnings.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "payrollWageItemId": { "description": "The payroll wage item that defines how this employee is paid (e.g., Regular Pay, Overtime Pay). This determines the payment scheme used for payroll calculations.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The hourly rate for this employee, represented as a decimal string.\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 hourly rate for this employee expressed as a percentage.", "example": "10.5", "type": "string" } }, "required": [ "payrollWageItemId" ], "additionalProperties": false } }, "useTimeDataToCreatePaychecks": { "description": "Indicates whether this employee is using time-tracking data to create paychecks.", "example": "uses_time_data", "type": "string", "enum": [ "does_not_use_time_data", "not_set", "uses_time_data" ] }, "sickHours": { "description": "The employee's sick hours, including how sick time is accrued and the total hours accrued.", "type": "object", "properties": { "hoursAvailable": { "description": "The total number of sick hours currently available for the employee to use, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M. Defaults to 0.", "example": "PT8H30M", "type": "string" }, "accrualPeriod": { "description": "How frequently the employee's sick hours are accrued.", "example": "accrues_per_paycheck", "type": "string", "enum": [ "accrues_annually", "accrues_hourly", "accrues_per_paycheck" ] }, "hoursAccruedPerPeriod": { "description": "The number of sick hours the employee will accrue per accrual period, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT8H0M", "type": "string" }, "maximumHours": { "description": "The maximum number of sick hours the employee can accrue, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT80H0M", "type": "string" }, "resetsHoursEachYear": { "description": "Indicates whether the employee's sick hours reset to zero at the beginning of the new year.", "example": false, "type": "boolean" }, "hoursUsed": { "description": "The number of sick hours the employee has used, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT2H45M", "type": "string" }, "accrualStartDate": { "description": "The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" } }, "additionalProperties": false }, "vacationHours": { "description": "The employee's vacation hours, including how vacation time is accrued and the total hours accrued.", "type": "object", "properties": { "hoursAvailable": { "description": "The total number of vacation hours currently available for the employee to use, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M. Defaults to 0.", "example": "PT8H30M", "type": "string" }, "accrualPeriod": { "description": "How frequently the employee's vacation hours are accrued.", "example": "accrues_per_paycheck", "type": "string", "enum": [ "accrues_annually", "accrues_hourly", "accrues_per_paycheck" ] }, "hoursAccruedPerPeriod": { "description": "The number of vacation hours the employee will accrue per accrual period, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT8H0M", "type": "string" }, "maximumHours": { "description": "The maximum number of vacation hours the employee can accrue, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT80H0M", "type": "string" }, "resetsHoursEachYear": { "description": "Indicates whether the employee's vacation hours reset to zero at the beginning of the new year.", "example": false, "type": "boolean" }, "hoursUsed": { "description": "The number of vacation hours the employee has used, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT2H45M", "type": "string" }, "accrualStartDate": { "description": "The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" } }, "additionalProperties": false } }, "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" } }, "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an employee record that captures personal details, contact information, employment dates, and payroll settings in a single request so the employee is ready for scheduling, time tracking, and payroll processing.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/employees/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop employees record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an employee by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific employees by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop employees", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the employee to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the employee to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the employee 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" }, "isActive": { "description": "Indicates whether this employee is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "salutation": { "description": "The employee's formal salutation title that precedes their name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The employee's first name.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The employee's middle name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The employee's last name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "jobTitle": { "description": "The employee's job title.", "example": "Purchasing Manager", "type": "string" }, "supervisorId": { "description": "The employee's supervisor. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "department": { "description": "The employee's department. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "Sales", "type": "string" }, "description": { "description": "A description of this employee. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "This employee is a key employee.", "type": "string" }, "targetBonus": { "description": "The target bonus for this employee, represented as a decimal string. Found in the \"employment job details\" section of the employee's record in QuickBooks.", "example": "10000.00", "type": "string" }, "address": { "description": "The employee's address.\n\nIf the company uses QuickBooks Payroll for this employee, this address must specify a complete address, including city, state, ZIP (or postal) code, and at least one line of the street address.", "type": "object", "properties": { "line1": { "description": "The first line of the employee 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 employee 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 employee address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the employee 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 employee address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The U.S. state of the employee address. QuickBooks requires this field to be a U.S. state abbreviation (e.g., \"CA\" for California). See enum for all possible values.", "example": "CA", "type": "string", "enum": [ "none", "armed_forces_americas", "armed_forces_europe", "armed_forces_pacific", "AK", "AL", "AR", "AZ", "CA", "CO", "CT", "DC", "DE", "FL", "GA", "HI", "IA", "ID", "IL", "IN", "KS", "KY", "LA", "MA", "MD", "ME", "MI", "MN", "MO", "MS", "MT", "NB", "NC", "ND", "NE", "NH", "NJ", "NM", "NV", "NY", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VA", "VT", "WA", "WI", "WV", "WY" ] }, "postalCode": { "description": "The postal code or ZIP code of the employee address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the employee address.", "example": "United States", "type": "string" } }, "additionalProperties": false }, "printAs": { "description": "The name to use when printing this employee from QuickBooks. By default, this is the same as the `name` field.", "example": "John Doe", "type": "string" }, "phone": { "description": "The employee's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "mobile": { "description": "The employee's mobile phone number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "pager": { "description": "The employee's pager number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "pagerPin": { "description": "The employee's pager PIN.", "example": "1234", "type": "string" }, "alternatePhone": { "description": "The employee's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The employee's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The employee's email address.", "example": "employee@example.com", "type": "string" }, "customContactFields": { "description": "Additional custom contact fields for this employee, 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 } }, "emergencyContact": { "description": "The employee's emergency contacts.", "type": "object", "properties": { "primaryContact": { "description": "The employee's primary emergency contact.", "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" }, "relation": { "description": "The relationship of the employee to the employee.", "example": "spouse", "type": "string", "enum": [ "brother", "daughter", "father", "friend", "mother", "other", "partner", "sister", "son", "spouse" ] } }, "required": [ "name", "value" ], "additionalProperties": false }, "secondaryContact": { "description": "The employee's secondary emergency contact.", "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" }, "relation": { "description": "The relationship of the employee to the employee.", "example": "spouse", "type": "string", "enum": [ "brother", "daughter", "father", "friend", "mother", "other", "partner", "sister", "son", "spouse" ] } }, "required": [ "name", "value" ], "additionalProperties": false } }, "additionalProperties": false }, "employeeType": { "description": "The employee type. This affects payroll taxes - a statutory employee is defined as an employee by statute. Note that owners/partners are typically on the \"Other Names\" list in QuickBooks, but if listed as an employee their type will be `owner`.", "example": "regular", "type": "string", "enum": [ "officer", "owner", "regular", "statutory" ] }, "employmentStatus": { "description": "Indicates whether this employee is a part-time or full-time employee.", "example": "full_time", "type": "string", "enum": [ "full_time", "part_time" ] }, "overtimeExemptStatus": { "description": "Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA).\n", "example": "exempt", "type": "string", "enum": [ "exempt", "non_exempt" ] }, "keyEmployeeStatus": { "description": "Indicates whether this employee is a key employee.", "example": "key_employee", "type": "string", "enum": [ "key_employee", "non_key_employee" ] }, "hiredDate": { "description": "The date this employee was hired, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "originalHireDate": { "description": "The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "adjustedServiceDate": { "description": "The adjusted service date for this employee, in ISO 8601 format (YYYY-MM-DD). This date accounts for previous employment periods or leaves that affect seniority.", "example": "2024-01-01", "type": "string", "format": "date" }, "terminationDate": { "description": "The date this employee's employment ended with the company, in ISO 8601 format (YYYY-MM-DD). This is also known as the released date or separation date.", "example": "2024-01-01", "type": "string", "format": "date" }, "birthDate": { "description": "This employee's date of birth, in ISO 8601 format (YYYY-MM-DD).", "example": "1990-01-01", "type": "string", "format": "date" }, "usCitizenshipStatus": { "description": "Indicates whether this employee is a U.S. citizen.", "example": "citizen", "type": "string", "enum": [ "citizen", "non_citizen" ] }, "ethnicity": { "description": "This employee's ethnicity.", "example": "asian", "type": "string", "enum": [ "american_indian", "asian", "black", "hawaiian", "hispanic", "white", "two_or_more_races" ] }, "disabilityStatus": { "description": "Indicates whether this employee is disabled.", "example": "disabled", "type": "string", "enum": [ "disabled", "non_disabled" ] }, "disabilityDescription": { "description": "A description of this employee's disability.", "example": "Cerebral Palsy", "type": "string" }, "i9OnFileStatus": { "description": "Indicates whether this employee's I-9 is on file.", "example": "on_file", "type": "string", "enum": [ "on_file", "not_on_file" ] }, "workAuthorizationExpirationDate": { "description": "The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "usVeteranStatus": { "description": "Indicates whether this employee is a U.S. veteran.", "example": "veteran", "type": "string", "enum": [ "veteran", "non_veteran" ] }, "militaryStatus": { "description": "This employee's military status if they are a U.S. veteran.", "example": "active", "type": "string", "enum": [ "active", "reserve" ] }, "accountNumber": { "description": "The employee'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 employee.", "example": "This employee is a key employee.", "type": "string" }, "additionalNotes": { "description": "Additional notes about this employee.", "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 } }, "billingRateId": { "description": "The employee's billing rate, used to override service item rates in time tracking activities.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "employeePayroll": { "description": "The employee's payroll information.\n\n**IMPORTANT**: QuickBooks Desktop requires the connected app to have personal data access enabled to update this field. If updating this field fails with a personal data permission error, confirm this setting is enabled in QuickBooks Desktop: sign in as Admin in Single-User Mode and go to `Edit > Preferences > Integrated Applications > Company Preferences`, select the app, click `Properties`, then check \"Allow this application to access personal data such as Social Security Numbers and customer credit card information\".", "type": "object", "properties": { "payPeriod": { "description": "How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks.", "example": "weekly", "type": "string", "enum": [ "biweekly", "daily", "monthly", "quarterly", "semimonthly", "weekly", "yearly" ] }, "classId": { "description": "The employee'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 }, "deleteAllEarnings": { "description": "When `true`, deletes all earnings records for this employee.", "example": false, "type": "boolean" }, "earnings": { "description": "The employee's earnings.\n\n**IMPORTANT**: When updating employees, if you include any earnings records in your update request, QuickBooks will delete all existing earnings records for this employee and replace them with the new records you provide. If you do not include any earnings records, the existing earnings records will remain unchanged. To delete all earnings records without adding new ones, set the `deleteAllEarnings` field to `true`.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "payrollWageItemId": { "description": "The payroll wage item that defines how this employee is paid (e.g., Regular Pay, Overtime Pay). This determines the payment scheme used for payroll calculations.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "rate": { "description": "The hourly rate for this employee, represented as a decimal string.\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 hourly rate for this employee expressed as a percentage.", "example": "10.5", "type": "string" } }, "required": [ "payrollWageItemId" ], "additionalProperties": false } }, "useTimeDataToCreatePaychecks": { "description": "Indicates whether this employee is using time-tracking data to create paychecks.", "example": "uses_time_data", "type": "string", "enum": [ "does_not_use_time_data", "not_set", "uses_time_data" ] }, "sickHours": { "description": "The employee's sick hours, including how sick time is accrued and the total hours accrued.", "type": "object", "properties": { "hoursAvailable": { "description": "The total number of sick hours currently available for the employee to use, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M. Defaults to 0.", "example": "PT8H30M", "type": "string" }, "accrualPeriod": { "description": "How frequently the employee's sick hours are accrued.", "example": "accrues_per_paycheck", "type": "string", "enum": [ "accrues_annually", "accrues_hourly", "accrues_per_paycheck" ] }, "hoursAccruedPerPeriod": { "description": "The number of sick hours the employee will accrue per accrual period, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT8H0M", "type": "string" }, "maximumHours": { "description": "The maximum number of sick hours the employee can accrue, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT80H0M", "type": "string" }, "resetsHoursEachYear": { "description": "Indicates whether the employee's sick hours reset to zero at the beginning of the new year.", "example": false, "type": "boolean" }, "hoursUsed": { "description": "The number of sick hours the employee has used, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT2H45M", "type": "string" }, "accrualStartDate": { "description": "The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" } }, "additionalProperties": false }, "vacationHours": { "description": "The employee's vacation hours, including how vacation time is accrued and the total hours accrued.", "type": "object", "properties": { "hoursAvailable": { "description": "The total number of vacation hours currently available for the employee to use, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M. Defaults to 0.", "example": "PT8H30M", "type": "string" }, "accrualPeriod": { "description": "How frequently the employee's vacation hours are accrued.", "example": "accrues_per_paycheck", "type": "string", "enum": [ "accrues_annually", "accrues_hourly", "accrues_per_paycheck" ] }, "hoursAccruedPerPeriod": { "description": "The number of vacation hours the employee will accrue per accrual period, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT8H0M", "type": "string" }, "maximumHours": { "description": "The maximum number of vacation hours the employee can accrue, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT80H0M", "type": "string" }, "resetsHoursEachYear": { "description": "Indicates whether the employee's vacation hours reset to zero at the beginning of the new year.", "example": false, "type": "boolean" }, "hoursUsed": { "description": "The number of vacation hours the employee has used, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.", "example": "PT2H45M", "type": "string" }, "accrualStartDate": { "description": "The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an employee record, allowing you to revise contact details, employment status dates, supervisory assignments, payroll configuration, and additional notes to keep workforce data current.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/estimates": { "get": { "summary": "List QuickBooks Desktop estimates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return. Mirror mode: default/max 100. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response. Mirror mode: {\"type\":\"string\",\"maxLength\":12000}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop. Mirror mode: {\"type\":\"string\",\"format\":\"date-time\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound. Mirror mode: {\"type\":\"string\",\"format\":\"date\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion. Mirror mode: {\"type\":\"boolean\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "transactionDate" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "transactionDateBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorList" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of estimates. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "customerId", "contactId", "transactionDateFrom", "transactionDateBefore", "refNumber", "includeLineItems", "active" ] }, "post": { "summary": "Create QuickBooks Desktop estimates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this estimate.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "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": 36 }, "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": 36 }, "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 } } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedEstimatesCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new estimate.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": { "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } } } }, "/api/qbd/v1/estimates/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop estimates record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "includeLineItems", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorDetail" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an estimate by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific estimates by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "includeLineItems" ] }, "post": { "summary": "Update QuickBooks Desktop estimates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the estimate to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the estimate to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": 36 }, "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": 36 }, "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": 36 }, "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 } } }, "required": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedEstimatesUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing estimate.\n\n**NOTE:** If you include `lines` or `lineGroups`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": { "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } } }, "delete": { "summary": "Delete QuickBooks Desktop estimates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the estimate to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the estimate to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a an estimate. The deletion will fail if the estimate is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/inventory-adjustments": { "get": { "summary": "List QuickBooks Desktop inventory-adjustments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of inventory adjustments.\n\n**NOTE:** QuickBooks Desktop does not support pagination for inventory adjustments; hence, there is no `cursor` parameter. Users typically have few inventory adjustments.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop inventory-adjustments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "description": "The account to which this inventory adjustment is posted for tracking inventory value changes.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this inventory adjustment, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this inventory adjustment, 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": "INVADJ-1234", "type": "string", "maxLength": 11 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this inventory adjustment is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customerId": { "description": "The customer or customer-job associated with this inventory adjustment.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The inventory adjustment'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 inventory adjustment's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this inventory adjustment.", "example": "Adjusted quantity due to physical count discrepancy", "type": "string" }, "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 adjustment's item lines, each representing the adjustment of an inventory item's quantity, value, serial number, or lot number.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The inventory item associated with this inventory adjustment line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "adjustQuantity": { "description": "Adjusts the inventory quantity of this inventory item either by setting a new quantity or by adjusting the current quantity up or down.", "type": "object", "properties": { "newQuantity": { "description": "The new quantity for the inventory item associated with this inventory adjustment line.", "example": 10, "type": "number" }, "quantityDifference": { "description": "Either a positive or negative number that shows the change in quantity for the inventory item associated with this inventory adjustment line. A positive number increases the quantity, while a negative number decreases it.", "example": 5, "type": "number" }, "serialNumber": { "description": "The serial number of the item associated with this inventory adjustment 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 inventory adjustment line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this inventory adjustment line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this inventory adjustment line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "additionalProperties": false }, "adjustValue": { "description": "Adjusts the total value of the entire stock of this inventory item by setting a new monetary value, and optionally by setting a new quantity.", "type": "object", "properties": { "newQuantity": { "description": "The new quantity for the inventory item associated with this inventory adjustment line.", "example": 10, "type": "number" }, "quantityDifference": { "description": "Either a positive or negative number that shows the change in quantity for the inventory item associated with this inventory adjustment line. A positive number increases the quantity, while a negative number decreases it.", "example": 5, "type": "number" }, "newValue": { "description": "The new total value of the entire stock of the inventory item associated with this inventory adjustment line.\n\n**NOTE**: The new value does _not_ have to equal `quantityOnHand` times `purchaseCost`.", "example": "100.00", "type": "string" }, "valueDifference": { "description": "Either a positive or negative number that shows the change in the total value of the entire stock of the inventory item associated with this inventory adjustment line. A positive number increases the value, while a negative number decreases it.", "example": 7, "type": "number" } }, "additionalProperties": false }, "adjustSerialNumber": { "description": "Adjusts the serial number of this inventory adjustment line. This is used for tracking individual units of serialized inventory items.", "type": "object", "properties": { "addSerialNumber": { "description": "The serial number, which represents a unique unit of the inventory item associated with this inventory adjustment line, to add to inventory.", "example": "123456", "type": "string" }, "removeSerialNumber": { "description": "The serial number, which represents a unique unit of the inventory item associated with this inventory adjustment line, to remove from inventory.", "example": "123456", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this inventory adjustment line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this inventory adjustment line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "additionalProperties": false }, "adjustLotNumber": { "description": "Adjusts the lot number of this inventory adjustment line.", "type": "object", "properties": { "lotNumber": { "description": "The lot number of the item associated with this inventory adjustment line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "adjustCount": { "description": "The amount to adjust the count of the inventory item associated with this inventory adjustment line.", "example": 2, "type": "number" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this inventory adjustment line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this inventory adjustment line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "additionalProperties": false } }, "required": [ "itemId" ], "additionalProperties": false } } }, "required": [ "accountId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an inventory adjustment to correct on-hand quantities or values. QuickBooks requires single-user mode unless you're on Enterprise with Advanced Inventory enabled.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/inventory-adjustments/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop inventory-adjustments record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an inventory adjustment by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific inventory adjustments by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop inventory-adjustments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the inventory adjustment to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the inventory adjustment to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the inventory adjustment 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" }, "accountId": { "description": "The account to which this inventory adjustment is posted for tracking inventory value changes.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this inventory adjustment is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this inventory adjustment, 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 inventory adjustment, 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": "INVADJ-1234", "type": "string", "maxLength": 11 }, "customerId": { "description": "The customer or customer-job associated with this inventory adjustment.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The inventory adjustment'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 inventory adjustment's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this inventory adjustment.", "example": "Adjusted quantity due to physical count discrepancy", "type": "string" }, "lines": { "description": "The inventory adjustment's item lines, each representing the adjustment of an inventory item's quantity, value, serial number, or lot number.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the inventory adjustment with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 inventory adjustment line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new inventory adjustment lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The inventory item associated with this inventory adjustment line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this inventory adjustment 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 inventory adjustment line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "adjustCount": { "description": "The amount to adjust the count of the inventory item associated with this inventory adjustment line.", "example": 2, "type": "number" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this inventory adjustment line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this inventory adjustment line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "quantityDifference": { "description": "Either a positive or negative number that shows the change in quantity for the inventory item associated with this inventory adjustment line. A positive number increases the quantity, while a negative number decreases it.", "example": 5, "type": "number" }, "valueDifference": { "description": "Either a positive or negative number that shows the change in the total value of the entire stock of the inventory item associated with this inventory adjustment line. A positive number increases the value, while a negative number decreases it.", "example": 7, "type": "number" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing inventory adjustment.\n\n**NOTE:** If you include `lines`, QuickBooks Desktop replaces that line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop inventory-adjustments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the inventory adjustment to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the inventory adjustment to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a an inventory adjustment. The deletion will fail if the inventory adjustment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/inventory-assembly-items": { "get": { "summary": "List QuickBooks Desktop inventory-assembly-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of inventory assembly items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop inventory-assembly-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedInventoryAssemblyItemsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an inventory assembly item that bundles existing inventory items.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/inventory-assembly-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop inventory-assembly-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an inventory assembly item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific inventory assembly items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop inventory-assembly-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the inventory assembly item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the inventory assembly item to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedInventoryAssemblyItemsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an inventory assembly item. If you change the income account, set `updateExistingTransactionsIncomeAccount` to true so QuickBooks applies the new account to existing transactions that use the assembly.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/inventory-items": { "get": { "summary": "List QuickBooks Desktop inventory-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of inventory items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop inventory-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedInventoryItemsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new inventory item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/inventory-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop inventory-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an inventory item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific inventory items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop inventory-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the inventory item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the inventory item to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedInventoryItemsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an inventory item. If you switch the income account, set `updateExistingTransactionsIncomeAccount` to true so QuickBooks applies the new account to existing transactions that reference the item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/inventory-sites": { "get": { "summary": "List QuickBooks Desktop inventory-sites", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of inventory sites.\n\n**NOTE:** QuickBooks Desktop does not support pagination for inventory sites; hence, there is no `cursor` parameter. Users typically have few inventory sites.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop inventory-sites", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this inventory site, unique across all inventory sites.\n\n**NOTE**: Inventory sites 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": "Stockroom" }, "isActive": { "description": "Indicates whether this inventory site 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 inventory site one level above this one in the hierarchy.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "description": { "description": "A description of this inventory site.", "example": "Main Stockroom for Electronics", "type": "string" }, "email": { "description": "The inventory site's email address.", "example": "inventory-site@example.com", "type": "string" }, "address": { "description": "The inventory site's address.", "type": "object", "properties": { "line1": { "description": "The first line of the site 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 site 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 site address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the site address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the site 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 site address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the site address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the site address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the site address.", "example": "United States", "type": "string" } }, "additionalProperties": false } }, "required": [ "name" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an inventory site for companies using QuickBooks Enterprise with Advanced Inventory.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/inventory-sites/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop inventory-sites record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an inventory site by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific inventory sites by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop inventory-sites", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the inventory site to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the inventory site to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the inventory site 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 inventory site, unique across all inventory sites.\n\n**NOTE**: Inventory sites 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": "Stockroom", "type": "string", "maxLength": 31 }, "isActive": { "description": "Indicates whether this inventory site is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "parentId": { "description": "The parent inventory site one level above this one in the hierarchy.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "description": { "description": "A description of this inventory site.", "example": "Main Stockroom for Electronics", "type": "string" }, "contact": { "description": "The name of the primary contact person for this inventory site.", "example": "Jane Smith", "type": "string" }, "phone": { "description": "The inventory site's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "fax": { "description": "The inventory site's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The inventory site's email address.", "example": "inventory-site@example.com", "type": "string" }, "address": { "description": "The inventory site's address.", "type": "object", "properties": { "line1": { "description": "The first line of the site 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 site 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 site address, if needed.\n\nMaximum length: 41 characters.", "example": "Suite 100", "type": "string", "maxLength": 41 }, "line4": { "description": "The fourth line of the site address, if needed.\n\nMaximum length: 41 characters.", "example": "", "type": "string", "maxLength": 41 }, "line5": { "description": "The fifth line of the site 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 site address.\n\nMaximum length: 31 characters.", "example": "San Francisco", "type": "string", "maxLength": 31 }, "state": { "description": "The state, county, province, or region name of the site address.\n\nMaximum length: 21 characters.", "example": "CA", "type": "string", "maxLength": 21 }, "postalCode": { "description": "The postal code or ZIP code of the site address.\n\nMaximum length: 13 characters.", "example": "94110", "type": "string", "maxLength": 13 }, "country": { "description": "The country name of the site address.", "example": "United States", "type": "string" } }, "additionalProperties": false } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing inventory site.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/invoices": { "get": { "summary": "List QuickBooks Desktop invoices", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return. Mirror mode: default/max 100. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response. Mirror mode: {\"type\":\"string\",\"maxLength\":12000}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop. Mirror mode: {\"type\":\"string\",\"format\":\"date-time\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound. Mirror mode: {\"type\":\"string\",\"format\":\"date\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "enum": [ "all", "paid", "unpaid" ], "description": "Filters payable or receivable transactions by paid, unpaid, or all payment status." }, "required": false, "name": "paymentStatus", "in": "query", "description": "Filters payable or receivable transactions by paid, unpaid, or all payment status." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion. Mirror mode: {\"type\":\"boolean\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "transactionDate" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "transactionDateBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "dueDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "dueDateBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "isPaid", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "isPending", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorList" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of invoices. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "customerId", "contactId", "transactionDateFrom", "transactionDateBefore", "refNumber", "includeLineItems", "dueDateFrom", "dueDateBefore", "isPaid", "isPending" ] }, "post": { "summary": "Create invoice in QuickBooks Desktop", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this invoice.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "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": 36 }, "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": 36, "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": 36 }, "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 } } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedInvoicesCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the invoice. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the invoice. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an invoice to bill a customer when goods or services were delivered before payment. Use a sales receipt instead if the sale was paid in full.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": { "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } } } }, "/api/qbd/v1/invoices/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop invoices record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "includeLineItems", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorDetail" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an invoice by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific invoices by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "includeLineItems" ] }, "post": { "summary": "Update QuickBooks Desktop invoices", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the invoice to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the invoice to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": 36 }, "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": 36 }, "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": 36 }, "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 } } }, "required": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedInvoicesUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing invoice.\n\n**NOTE:** If you include `lines` or `lineGroups`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": { "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } } }, "delete": { "summary": "Delete QuickBooks Desktop invoices", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the invoice to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the invoice to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a an invoice. The deletion will fail if the invoice is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/item-groups": { "get": { "summary": "List QuickBooks Desktop item-groups", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of item groups. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop item-groups", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedItemGroupsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new item group.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/item-groups/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop item-groups record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an item group by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific item groups by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop item-groups", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the item group to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the item group to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedItemGroupsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing item group.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/item-receipts": { "get": { "summary": "List QuickBooks Desktop item-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of item receipts. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop item-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "description": "The vendor who sent this item receipt for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this item receipt is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this item receipt is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this item receipt, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this item receipt, 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: 20 characters.", "example": "RECEIPT-1234", "type": "string", "maxLength": 20 }, "memo": { "description": "A memo or note for this item receipt.", "example": "Received 100 units of Product X from Vendor Y", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this item receipt, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the item receipt's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this item receipt'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 purchase orders that you wish to link to this item receipt. 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 item receipt's lines, if available.\n\nTransactions can only be linked when creating this item receipt and cannot be unlinked later.\n\nYou can use both `linkToTransactionIds` (on this item receipt) 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 item receipt and check the `linkedTransactions` response field. If fetching a list of item receipts, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 36 } }, "expenseLines": { "description": "The item receipt's expense lines, each representing one line in this expense.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the expense 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 } }, "itemLines": { "description": "The item receipt's item lines, each representing the purchase of a specific item or service.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this item 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. If the parent transaction is a bill or an item receipt, you can only link to purchase orders; QuickBooks does not support linking these transactions to other transaction types.\n\nTransaction lines can only be linked when creating this item line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this item 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 item 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 transaction and check the `linkedTransactions` response field. If fetching a list of transactions, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "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 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item 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 } }, "itemGroupLines": { "description": "The item receipt's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this item group 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 group associated with this item group line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item group 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 } } }, "required": [ "itemGroupId" ], "additionalProperties": false } } }, "required": [ "vendorId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an item receipt to record inventory received from a vendor. You can link it to a purchase order during creation to pull in the order's lines automatically and update quantities, but that link can't be added later with an update.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/item-receipts/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop item-receipts record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an item receipt by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific item receipts by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop item-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the item receipt to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the item receipt to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the item receipt 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" }, "vendorId": { "description": "The vendor who sent this item receipt for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this item receipt is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this item receipt is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this item receipt, 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 item receipt, 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: 20 characters.", "example": "RECEIPT-1234", "type": "string", "maxLength": 20 }, "memo": { "description": "A memo or note for this item receipt.", "example": "Received 100 units of Product X from Vendor Y", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this item receipt, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the item receipt's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this item receipt'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" }, "clearExpenseLines": { "description": "When `true`, removes all existing expense lines associated with this item receipt. To modify or add individual expense lines, use the field `expenseLines` instead.", "example": false, "type": "boolean" }, "expenseLines": { "description": "The item receipt's expense lines, each representing one line in this expense.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing expense lines for the item receipt with this array. To keep any existing expense lines, you must include them in this array even if they have not changed. **Any expense lines not included will be removed.**\n\n2. To add a new expense line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any expense lines, 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 expense line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new expense lines you wish to add.", "example": "456DEF-1234567890" }, "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this item receipt. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "itemLines": { "description": "The item receipt's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item receipt with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "itemGroupLines": { "description": "The item receipt's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item group lines for the item receipt with this array. To keep any existing item group lines, you must include them in this array even if they have not changed. **Any item group lines not included will be removed.**\n\n2. To add a new item group line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item group lines, 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 item group line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item group lines you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this item group 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 }, "itemLines": { "description": "The item group line's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item group line with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing item receipt.\n\n**NOTE:** If you include `expenseLines`, `itemLines`, or `itemGroupLines`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop item-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the item receipt to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the item receipt to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a an item receipt. The deletion will fail if the item receipt is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/item-sites": { "get": { "summary": "List QuickBooks Desktop item-sites", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of item sites. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/item-sites/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop item-sites record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an item site by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific item sites by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/journal-entries": { "get": { "summary": "List QuickBooks Desktop journal-entries", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of journal entries. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop journal-entries", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionDate": { "type": "string", "format": "date", "description": "The date of this journal entry, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this journal entry, 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": "JE-1234", "type": "string", "maxLength": 11 }, "isAdjustment": { "description": "Indicates whether this journal entry is an adjustment entry. When `true`, QuickBooks retains the original entry information to maintain an audit trail of the adjustments.", "example": false, "type": "boolean" }, "isHomeCurrencyAdjustment": { "description": "Indicates whether this journal entry is an adjustment made in the company's home currency for a transaction that was originally recorded in a foreign currency.", "example": false, "type": "boolean" }, "areAmountsEnteredInHomeCurrency": { "description": "Indicates whether the amounts in this journal entry were entered in the company's home currency rather than a foreign currency. When `true`, amounts are in the home currency regardless of the `currency` field.", "example": false, "type": "boolean" }, "currencyId": { "description": "The journal entry'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 }, "exchangeRate": { "description": "The market exchange rate between this journal entry'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" }, "debitLines": { "description": "The journal entry's debit lines.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The account to which this journal debit line is being debited. This will decrease the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this journal debit line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this journal debit line.", "example": "Monthly utility bill settlement", "type": "string" }, "entityId": { "description": "The customer, vendor, employee, or other entity associated with this journal debit line.\n\n**IMPORTANT**: If the journal debit line's `account` is an Accounts Receivable (A/R) account, this field must refer to a customer. If the journal debit line's `account` is an Accounts Payable (A/P) account, this field must refer to a vendor. If these requirements are not met, QuickBooks Desktop will not record the transaction.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The journal debit 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 journal debit lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this journal debit line'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 }, "billingStatus": { "description": "The billing status of this journal debit line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" } }, "required": [ "accountId" ], "additionalProperties": false } }, "creditLines": { "description": "The journal entry's credit lines.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The account to which this journal credit line is being credited. This will increase the balance of this account.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this journal credit line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this journal credit line.", "example": "Allocated funds for office lease payment", "type": "string" }, "entityId": { "description": "The customer, vendor, employee, or other entity associated with this journal credit line.\n\n**IMPORTANT**: If the journal credit line's `account` is an Accounts Receivable (A/R) account, this field must refer to a customer. If the journal credit line's `account` is an Accounts Payable (A/P) account, this field must refer to a vendor. If these requirements are not met, QuickBooks Desktop will not record the transaction.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The journal credit 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 journal credit lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this journal credit line'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 }, "billingStatus": { "description": "The billing status of this journal credit line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" } }, "required": [ "accountId" ], "additionalProperties": false } } }, "required": [ "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a journal entry with balanced debit and credit lines. QuickBooks Desktop requires total debits to equal total credits, and any line that posts to Accounts Receivable or Accounts Payable must include the related customer or vendor reference.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/journal-entries/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop journal-entries record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a journal entry by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific journal entries by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop journal-entries", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the journal entry to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the journal entry to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the journal entry 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" }, "transactionDate": { "description": "The date of this journal entry, 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 journal entry, 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": "JE-1234", "type": "string", "maxLength": 11 }, "isAdjustment": { "description": "Indicates whether this journal entry is an adjustment entry. When `true`, QuickBooks retains the original entry information to maintain an audit trail of the adjustments.", "example": false, "type": "boolean" }, "areAmountsEnteredInHomeCurrency": { "description": "Indicates whether the amounts in this journal entry were entered in the company's home currency rather than a foreign currency. When `true`, amounts are in the home currency regardless of the `currency` field.", "example": false, "type": "boolean" }, "currencyId": { "description": "The journal entry'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 }, "exchangeRate": { "description": "The market exchange rate between this journal entry'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 journal entry's credit and debit lines.\n\n**IMPORTANT**: When updating journal entries, you must include ALL existing journal lines (both credit and debit) in your update request, even if you only want to modify a single line. QuickBooks will automatically delete any existing lines that are not included in the update request, which is why all lines must be provided in a single array when updating.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of an existing journal line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new journal lines you wish to add.", "example": "456DEF-1234567890" }, "journalLineType": { "description": "The type of journal line (debit or credit).", "example": "debit", "type": "string", "enum": [ "debit", "credit" ] }, "accountId": { "description": "The account to which this journal line is being credited or debited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this journal line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this journal line.", "example": "Allocated funds for office lease payment", "type": "string" }, "entityId": { "description": "The customer, vendor, employee, or other entity associated with this journal line.\n\n**IMPORTANT**: If the journal line's `account` is an Accounts Receivable (A/R) account, this field must refer to a customer. If the journal line's `account` is an Accounts Payable (A/P) account, this field must refer to a vendor. If these requirements are not met, QuickBooks Desktop will not record the transaction.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The journal 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 journal lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this journal line'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 }, "billingStatus": { "description": "The billing status of this journal line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing journal entry. Keep the debits and credits in balance, and include the related customer or vendor on any A/R or A/P line you submit in the update body.\n\n**NOTE:** If you include `lines`, QuickBooks Desktop replaces that line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop journal-entries", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the journal entry to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the journal entry to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a journal entry. The deletion will fail if the journal entry is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/non-inventory-items": { "get": { "summary": "List QuickBooks Desktop non-inventory-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of non-inventory items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop non-inventory-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedNonInventoryItemsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new non-inventory item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/non-inventory-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop non-inventory-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a non-inventory item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific non-inventory items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop non-inventory-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the non-inventory item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the non-inventory item to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 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 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedNonInventoryItemsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a non-inventory item. You can modify either `salesOrPurchaseDetails` or `salesAndPurchaseDetails`, but the item must keep the same configuration it was created with. When you change `postingAccount`, `incomeAccount`, or `expenseAccount`, include the matching `updateExistingTransactions...` flag so QuickBooks applies the new account to existing transactions and doesn’t reject the update when historical activity is present.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/other-charge-items": { "get": { "summary": "List QuickBooks Desktop other-charge-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of other charge items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop other-charge-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedOtherChargeItemsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new other charge item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/other-charge-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop other-charge-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an other charge item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific other charge items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop other-charge-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the other charge item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the other charge item to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedOtherChargeItemsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing other charge item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/other-names": { "get": { "summary": "List QuickBooks Desktop other-names", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of other-names.\n\n**NOTE:** QuickBooks Desktop does not support pagination for other-names; hence, there is no `cursor` parameter. Users typically have few other-names.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop other-names", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this other-name, unique across all other-names.\n\n**NOTE**: Other-names 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": "John Doe" }, "isActive": { "description": "Indicates whether this other-name is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "companyName": { "description": "The name of the company associated with this other-name. 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 other-name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The first name of the contact person for this other-name.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The middle name of the contact person for this other-name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The last name of the contact person for this other-name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "address": { "description": "The other-name's 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 other-name's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "alternatePhone": { "description": "The other-name's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The other-name's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The other-name's email address.", "example": "other-name@example.com", "type": "string" }, "contact": { "description": "The name of the primary contact person for this other-name.", "example": "Jane Smith", "type": "string" }, "alternateContact": { "description": "The name of a alternate contact person for this other-name.", "example": "Bob Johnson", "type": "string" }, "accountNumber": { "description": "The other-name'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 other-name.", "example": "This employee is a key employee.", "type": "string" }, "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 } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new other-name.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/other-names/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop other-names record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an other-name by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific other-names by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop other-names", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the other-name to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the other-name to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the other-name 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 other-name, unique across all other-names.\n\n**NOTE**: Other-names 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": "John Doe", "type": "string", "maxLength": 31 }, "isActive": { "description": "Indicates whether this other-name is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "companyName": { "description": "The name of the company associated with this other-name. 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 other-name, such as \"Mr.\", \"Ms.\", or \"Dr.\".", "example": "Dr.", "type": "string" }, "firstName": { "description": "The first name of the contact person for this other-name.\n\nMaximum length: 25 characters.", "example": "John", "type": "string", "maxLength": 25 }, "middleName": { "description": "The middle name of the contact person for this other-name.\n\nMaximum length: 5 characters.", "example": "A.", "type": "string", "maxLength": 5 }, "lastName": { "description": "The last name of the contact person for this other-name.\n\nMaximum length: 25 characters.", "example": "Doe", "type": "string", "maxLength": 25 }, "address": { "description": "The other-name's 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 other-name's primary telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-123-4567", "type": "string", "maxLength": 21 }, "alternatePhone": { "description": "The other-name's alternate telephone number.\n\nMaximum length: 21 characters.", "example": "+1-555-987-6543", "type": "string", "maxLength": 21 }, "fax": { "description": "The other-name's fax number.\n\nMaximum length: 21 characters.", "example": "+1-555-555-1212", "type": "string", "maxLength": 21 }, "email": { "description": "The other-name's email address.", "example": "other-name@example.com", "type": "string" }, "contact": { "description": "The name of the primary contact person for this other-name.", "example": "Jane Smith", "type": "string" }, "alternateContact": { "description": "The name of a alternate contact person for this other-name.", "example": "Bob Johnson", "type": "string" }, "accountNumber": { "description": "The other-name'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 other-name.", "example": "This employee is a key employee.", "type": "string" } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing other-name.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/payment-methods": { "get": { "summary": "List QuickBooks Desktop payment-methods", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of payment methods.\n\n**NOTE:** QuickBooks Desktop does not support pagination for payment methods; hence, there is no `cursor` parameter. Users typically have few payment methods.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop payment-methods", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this payment method, unique across all payment methods.\n\n**NOTE**: Payment methods 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": "Cash" }, "isActive": { "description": "Indicates whether this payment method is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "paymentMethodType": { "description": "This payment method's type.", "example": "cash", "type": "string", "enum": [ "american_express", "cash", "check", "debit_card", "discover", "e_check", "gift_card", "master_card", "other", "other_credit_card", "visa" ] } }, "required": [ "name", "paymentMethodType" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new payment method.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/payment-methods/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop payment-methods record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a payment method by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific payment methods by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/payroll-wage-items": { "get": { "summary": "List QuickBooks Desktop payroll-wage-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of payroll wage items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop payroll-wage-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this payroll wage item, unique across all payroll wage items.\n\n**NOTE**: Payroll wage items 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": "Regular Pay" }, "isActive": { "description": "Indicates whether this payroll wage item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "wageType": { "description": "Categorizes how this payroll wage item calculates pay - can be hourly (regular, overtime, sick, or vacation), salary (regular, sick, or vacation), bonus, or commission based.", "example": "hourly_regular", "type": "string", "enum": [ "bonus", "commission", "hourly_overtime", "hourly_regular", "hourly_sick", "hourly_vacation", "salary_regular", "salary_sick", "salary_vacation" ] }, "overtimeMultiplier": { "description": "The overtime pay multiplier for this payroll wage item, represented as a decimal string. For example, `\"1.5\"` represents time-and-a-half pay.", "example": "1.5", "type": "string" }, "rate": { "description": "The default rate for this payroll wage item, represented as a decimal string. Only one of `rate` and `ratePercent` can be set.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "15.00", "type": "string" }, "ratePercent": { "description": "The default rate for this payroll wage item expressed as a percentage. Only one of `rate` and `ratePercent` can be set.", "example": "10", "type": "string" }, "expenseAccountId": { "description": "The expense account used to track wage expenses paid through this payroll wage item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "name", "wageType", "expenseAccountId" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new payroll wage item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/payroll-wage-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop payroll-wage-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a payroll wage item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific payroll wage items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/price-levels": { "get": { "summary": "List QuickBooks Desktop price-levels", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of price levels.\n\n**NOTE:** QuickBooks Desktop does not support pagination for price levels; hence, there is no `cursor` parameter. Users typically have few price levels.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop price-levels", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this price level, unique across all price levels.\n\n**NOTE**: Price levels 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": "Wholesale 20% Discount" }, "isActive": { "description": "Indicates whether this price level is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "fixedPercentage": { "description": "The fixed percentage adjustment applied to all items for this price level (instead of a per-item price level). Once you create the price level, you cannot change this.\n\nWhen this price level is applied to a customer, it automatically adjusts the `rate` and `amount` columns for applicable line items in sales orders and invoices for that customer. This value supports both positive and negative values - a value of \"20\" increases prices by 20%, while \"-10\" decreases prices by 10%.", "example": "-10.0", "type": "string" }, "perItemPriceLevels": { "description": "The per-item price level configurations for this price level.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this per-item price level. 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": 36 }, "customPrice": { "description": "The fixed amount custom price for this per-item price level that overrides the standard price for the specified item. Used when setting an absolute price value for the item in this price level.", "example": "19.99", "type": "string" }, "customPricePercent": { "description": "The fixed discount percentage for this per-item price level that modifies the specified item's standard price. Used to create a fixed percentage markup or discount specific to this item within this price level.", "example": "15.0", "type": "string" }, "adjustPercentage": { "description": "The percentage adjustment for this per-item price level when using relative pricing. Specifies a percentage to modify pricing, using positive values (e.g., \"20\") to increase prices by that percentage, or negative values (e.g., \"-10\") to apply a discount.", "example": "-10.0", "type": "string" }, "adjustRelativeTo": { "description": "The base value reference for this per-item price level's percentage adjustment. Specifies which price to use as the starting point for the adjustment calculation in the price level.\n\n**NOTE:** The price level must use either a fixed pricing approach (`customPrice` or `customPricePercent`) or a relative adjustment approach (`adjustPercentage` with `adjustRelativeTo`) when configuring per-item price levels.", "example": "standard_price", "type": "string", "enum": [ "cost", "current_custom_price", "standard_price" ] } }, "required": [ "itemId" ], "additionalProperties": false } }, "currencyId": { "description": "The price level'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 } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new price level.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/price-levels/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop price-levels record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a price level by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific price levels by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop price-levels", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the price level to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the price level to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the price level 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 price level, unique across all price levels.\n\n**NOTE**: Price levels 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": "Wholesale 20% Discount", "type": "string", "maxLength": 31 }, "isActive": { "description": "Indicates whether this price level is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "fixedPercentage": { "description": "The fixed percentage adjustment applied to all items for this price level (instead of a per-item price level). Once you create the price level, you cannot change this.\n\nWhen this price level is applied to a customer, it automatically adjusts the `rate` and `amount` columns for applicable line items in sales orders and invoices for that customer. This value supports both positive and negative values - a value of \"20\" increases prices by 20%, while \"-10\" decreases prices by 10%.", "example": "-10.0", "type": "string" }, "perItemPriceLevels": { "description": "The per-item price level configurations for this price level.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this per-item price level. 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": 36 }, "customPrice": { "description": "The fixed amount custom price for this per-item price level that overrides the standard price for the specified item. Used when setting an absolute price value for the item in this price level.", "example": "19.99", "type": "string" }, "customPricePercent": { "description": "The fixed discount percentage for this per-item price level that modifies the specified item's standard price. Used to create a fixed percentage markup or discount specific to this item within this price level.", "example": "15.0", "type": "string" }, "adjustPercentage": { "description": "The percentage adjustment for this per-item price level when using relative pricing. Specifies a percentage to modify pricing, using positive values (e.g., \"20\") to increase prices by that percentage, or negative values (e.g., \"-10\") to apply a discount.", "example": "-10.0", "type": "string" }, "adjustRelativeTo": { "description": "The base value reference for this per-item price level's percentage adjustment. Specifies which price to use as the starting point for the adjustment calculation in the price level.\n\n**NOTE:** The price level must use either a fixed pricing approach (`customPrice` or `customPricePercent`) or a relative adjustment approach (`adjustPercentage` with `adjustRelativeTo`) when configuring per-item price levels.", "example": "standard_price", "type": "string", "enum": [ "cost", "current_custom_price", "standard_price" ] } }, "required": [ "itemId" ], "additionalProperties": false } }, "currencyId": { "description": "The price level'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": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing price level.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/purchase-orders": { "get": { "summary": "List QuickBooks Desktop purchase-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of purchase orders. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop purchase-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "description": "The vendor who sent this purchase order for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The purchase 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 purchase order's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this purchase order is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipToEntityId": { "description": "The customer, vendor, employee, or other entity to whom this purchase order is to be shipped.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this purchase order when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this purchase order, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this purchase 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": "PO-1234", "type": "string", "maxLength": 11 }, "vendorAddress": { "description": "The address of the vendor who sent this purchase order.", "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 purchase 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 }, "termsId": { "description": "The purchase 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 purchase order must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "expectedDate": { "description": "The date on which shipment of this purchase order is expected to be completed, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "shippingMethodId": { "description": "The shipping method used for this purchase order, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this purchase 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 }, "memo": { "description": "A memo or note for this purchase order that appears in reports, but not on the purchase order.", "example": "Office supplies for September", "type": "string" }, "vendorMessage": { "description": "A message to be printed on this purchase order for the vendor to read.", "example": "Please include packing slip with shipment", "type": "string" }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this purchase order is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this purchase 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 purchase order, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the purchase order's individual lines.\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 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this purchase order. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase orders 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 purchase order. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase orders 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" }, "exchangeRate": { "description": "The market exchange rate between this purchase 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 purchase 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 purchase order.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this purchase 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": 36 }, "sku": { "description": "The purchase order line's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "description": { "description": "A description of this purchase order line.", "example": "Office chairs - Herman Miller Aeron (Black)", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this purchase 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 purchase 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 purchase 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" }, "classId": { "description": "The purchase 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 purchase order lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this purchase 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" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this purchase order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serviceDate": { "description": "The date on which the service for this purchase order 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 purchase 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 }, "overrideItemAccountId": { "description": "The account to use for this purchase order 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 purchase order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase 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 purchase order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase 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 purchase 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 purchase 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 purchase order.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The purchase 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": 36 }, "quantity": { "description": "The quantity of the item group associated with this purchase 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 purchase order 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 purchase order 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" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item group associated with this purchase order line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the purchase 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 } } }, "required": [ "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new purchase order.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/purchase-orders/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop purchase-orders record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a purchase order by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific purchase orders by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop purchase-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the purchase order to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the purchase order to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the purchase 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" }, "vendorId": { "description": "The vendor who sent this purchase order for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The purchase 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 purchase order's line items unless overridden at the line item level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this purchase order is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipToEntityId": { "description": "The customer, vendor, employee, or other entity to whom this purchase order is to be shipped.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "documentTemplateId": { "description": "The predefined template in QuickBooks that determines the layout and formatting for this purchase order when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this purchase 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 purchase 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": "PO-1234", "type": "string", "maxLength": 11 }, "vendorAddress": { "description": "The address of the vendor who sent this purchase order.", "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 purchase 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 }, "termsId": { "description": "The purchase 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 purchase order must be paid, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-31", "type": "string", "format": "date" }, "expectedDate": { "description": "The date on which shipment of this purchase order is expected to be completed, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01", "type": "string", "format": "date" }, "shippingMethodId": { "description": "The shipping method used for this purchase order, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this purchase 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 }, "isManuallyClosed": { "description": "Indicates whether this purchase order has been manually marked as closed, even if all items have not been received or the sale has not been cancelled. Once the purchase order is marked as closed, all of its line items become closed as well. You cannot change `isManuallyClosed` to `false` after the purchase order has been fully received.", "example": true, "type": "boolean" }, "memo": { "description": "A memo or note for this purchase order that appears in reports, but not on the purchase order.", "example": "Office supplies for September", "type": "string" }, "vendorMessage": { "description": "A message to be printed on this purchase order for the vendor to read.", "example": "Please include packing slip with shipment", "type": "string" }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this purchase order is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this purchase 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 purchase order, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the purchase order's individual lines.\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 }, "otherCustomField1": { "description": "A built-in custom field for additional information specific to this purchase order. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase orders 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 purchase order. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase orders 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" }, "exchangeRate": { "description": "The market exchange rate between this purchase 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 purchase 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 purchase 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 purchase order line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new purchase order lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this purchase 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": 36 }, "sku": { "description": "The purchase order line's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "description": { "description": "A description of this purchase order line.", "example": "Office chairs - Herman Miller Aeron (Black)", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this purchase 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 purchase 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 purchase 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 purchase 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" }, "classId": { "description": "The purchase 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 purchase order lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this purchase 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" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this purchase order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serviceDate": { "description": "The date on which the service for this purchase order 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 purchase 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 purchase order line has been manually marked as closed, even if this item has not been received or its sale has not been cancelled. If all the purchase order lines are marked as closed, the purchase order itself is marked as closed as well. You cannot change `isManuallyClosed` to `false` after the purchase order line has been fully received.", "example": true, "type": "boolean" }, "overrideItemAccountId": { "description": "The account to use for this purchase order 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 purchase order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase 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 purchase order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase 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 purchase 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 purchase 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 purchase order line group you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new purchase order line groups you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The purchase 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": 36 }, "quantity": { "description": "The quantity of the item group associated with this purchase 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 purchase 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 purchase 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 purchase 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 purchase 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 purchase order line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new purchase order lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this purchase 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": 36 }, "sku": { "description": "The purchase order line's stock keeping unit (SKU), which is sometimes the manufacturer's part number.", "example": "MPN-123456", "type": "string" }, "description": { "description": "A description of this purchase order line.", "example": "Office chairs - Herman Miller Aeron (Black)", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this purchase 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 purchase 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 purchase 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 purchase 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" }, "classId": { "description": "The purchase 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 purchase order lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this purchase 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" }, "inventorySiteLocationId": { "description": "The specific location (e.g., bin or shelf) within the inventory site where the item associated with this purchase order line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serviceDate": { "description": "The date on which the service for this purchase order 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 purchase 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 purchase order line has been manually marked as closed, even if this item has not been received or its sale has not been cancelled. If all the purchase order lines are marked as closed, the purchase order itself is marked as closed as well. You cannot change `isManuallyClosed` to `false` after the purchase order line has been fully received.", "example": true, "type": "boolean" }, "overrideItemAccountId": { "description": "The account to use for this purchase order 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 purchase order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase 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 purchase order line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all purchase 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 } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing purchase order.\n\n**NOTE:** If you include `lines` or `lineGroups`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop purchase-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the purchase order to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the purchase order to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a purchase order. The deletion will fail if the purchase order is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/receive-payments": { "get": { "summary": "List QuickBooks Desktop receive-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of receive-payments. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop receive-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job to which the payment for this receive-payment is credited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "receivablesAccountId": { "description": "The Accounts-Receivable (A/R) account to which this receive-payment 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 receive-payment 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 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this receive-payment, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this receive-payment, 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: 20 characters.", "example": "PAYMENT-1234", "type": "string", "maxLength": 20 }, "totalAmount": { "type": "string", "description": "The total monetary amount of this receive-payment, represented as a decimal string.\n\n**NOTE**: The sum of the `paymentAmount` amounts in the `applyToTransactions` array cannot exceed the `totalAmount`, or you will receive an error.\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" }, "exchangeRate": { "description": "The market exchange rate between this receive-payment'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" }, "paymentMethodId": { "description": "The receive-payment's payment method (e.g., cash, check, credit card).\n\n**NOTE**: If this receive-payment contains credit card transaction data supplied from QuickBooks Merchant Services (QBMS) transaction responses, you must specify a credit card payment method (e.g., \"Visa\", \"MasterCard\", etc.).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this receive-payment that will be displayed at the beginning of reports containing details about this receive-payment.", "example": "Payment received at store location - cash", "type": "string" }, "depositToAccountId": { "description": "The account where the funds for this receive-payment will be or have been deposited. If omitted, QuickBooks Desktop uses the default Undeposited Funds account configured in the company file.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditCardTransaction": { "description": "The credit card transaction data for this receive-payment's payment when using QuickBooks Merchant Services (QBMS). If specifying this field, you must also specify the `paymentMethod` field.", "type": "object", "properties": { "request": { "description": "The transaction request data originally supplied for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "number": { "type": "string", "description": "The credit card number. Must be masked with lower case \"x\" and no dashes.", "example": "xxxxxxxxxxxx1234" }, "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": { "type": "string", "description": "The cardholder's name on the card.", "example": "John Doe" }, "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" }, "commercialCardCode": { "description": "The commercial card code identifies the type of business credit card being used (purchase, corporate, or business) for Visa and Mastercard transactions only. When provided, this code may qualify the transaction for lower processing fees compared to the standard rates that apply when no code is specified.", "example": "corporate", "type": "string" }, "transactionMode": { "description": "Indicates whether this credit card transaction came from a card swipe (`card_present`) or not (`card_not_present`).", "example": "card_not_present", "type": "string", "enum": [ "card_not_present", "card_present" ], "default": "card_not_present" }, "transactionType": { "description": "The QBMS transaction type from which the current transaction data originated.", "example": "charge", "type": "string", "enum": [ "authorization", "capture", "charge", "refund", "voice_authorization" ] } }, "required": [ "number", "expirationMonth", "expirationYear", "name" ], "additionalProperties": false }, "response": { "description": "The transaction response data for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "statusCode": { "description": "The status code returned in the original QBMS transaction response for this credit card transaction.", "example": 0, "type": "number" }, "statusMessage": { "type": "string", "description": "The status message returned in the original QBMS transaction response for this credit card transaction.", "example": "Success" }, "creditCardTransactionId": { "type": "string", "description": "The ID returned from the credit card processor for this credit card transaction.", "example": "1234567890" }, "merchantAccountNumber": { "type": "string", "description": "The QBMS account number of the merchant who is running this transaction using the customer's credit card.", "example": "1234567890" }, "authorizationCode": { "description": "The authorization code returned from the credit card processor to indicate that this charge will be paid by the card issuer.", "example": "1234567890", "type": "string" }, "avsStreetStatus": { "description": "Indicates whether the street address supplied in the transaction request matches the customer's address on file at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "avsZipStatus": { "description": "Indicates whether the customer postal ZIP code supplied in the transaction request matches the customer's postal code recognized at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "cardSecurityCodeMatch": { "description": "Indicates whether the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "reconBatchId": { "description": "An internal ID returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": "1234567890", "type": "string" }, "paymentGroupingCode": { "description": "An internal code returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "paymentStatus": { "description": "Indicates whether this credit card transaction is known to have been successfully processed by the card issuer.", "example": "completed", "type": "string", "enum": [ "completed", "unknown" ] }, "transactionAuthorizedAt": { "type": "string", "description": "The date and time when the credit card processor authorized this credit card transaction.", "example": "2024-01-01 12:34:56 UTC" }, "transactionAuthorizationStamp": { "description": "An internal value for this credit card transaction, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "clientTransactionId": { "description": "A value returned from QBMS transactions for future use by the QuickBooks Reconciliation feature.", "example": "1234567890", "type": "string" } }, "required": [ "statusCode", "statusMessage", "creditCardTransactionId", "merchantAccountNumber", "paymentStatus", "transactionAuthorizedAt" ], "additionalProperties": false } }, "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" }, "isAutoApply": { "description": "When `true`, QuickBooks applies `totalAmount` to any outstanding transaction that exactly matches `totalAmount`. If no exact match is found, this receive-payment is applied to the oldest outstanding transaction for the customer-job. When `false`, QuickBooks records the payment but does not apply it to any specific transaction, causing the amount to appear as a credit on the customer-job's next transaction.\n\n**IMPORTANT**: You must specify either `isAutoApply` or `applyToTransactions` when creating a receive-payment, but never both.", "example": false, "default": false, "type": "boolean" }, "applyToTransactions": { "description": "The invoices to be paid by this receive-payment. This will create a link between this receive-payment and the specified invoices.\n\n**IMPORTANT**: In each `applyToTransactions` object, you must specify either `paymentAmount`, `applyCredits`, `discountAmount`, or any combination of these; if none of these are specified, you will receive an error for an empty transaction.\n\n**IMPORTANT**: The target invoice must have `isPaid=false`, otherwise, QuickBooks will report this object as \"cannot be found\".\n\n**NOTE**: You must specify either `isAutoApply` or `applyToTransactions` when creating a receive-payment, but never both.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the target transaction to which this payment is applied.", "example": "123ABC-1234567890" }, "paymentAmount": { "description": "The monetary amount to apply to the target 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": "25.00", "type": "string" }, "applyCredits": { "description": "Credits to apply to this target transaction, reducing its balance. This creates a link between this target transaction 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 target transaction and check the `linkedTransactions` response field. If fetching a list of target transactions, 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 } }, "discountAmount": { "description": "The monetary amount by which to reduce this target transaction's balance, 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": "50.00", "type": "string" }, "discountAccountId": { "description": "The financial account used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "discountClassId": { "description": "The class used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "transactionId" ], "additionalProperties": false } } }, "required": [ "customerId", "transactionDate", "totalAmount" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Records a customer payment and optionally applies it to specific invoices, discounts, or credits. All allocations must target the same accounts receivable account as those invoices, and each one has to include a payment amount, discount, or credit so QuickBooks can close out the balance.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/receive-payments/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop receive-payments record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a receive-payment by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific receive-payments by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop receive-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the receive-payment to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the receive-payment to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the receive-payment 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 to which the payment for this receive-payment is credited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "receivablesAccountId": { "description": "The Accounts-Receivable (A/R) account to which this receive-payment 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 receive-payment 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 }, "transactionDate": { "description": "The date of this receive-payment, 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 receive-payment, 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: 20 characters.", "example": "PAYMENT-1234", "type": "string", "maxLength": 20 }, "totalAmount": { "description": "The total monetary amount of this receive-payment, represented as a decimal string.\n\n**NOTE**: The sum of the `paymentAmount` amounts in the `applyToTransactions` array cannot exceed the `totalAmount`, or you will receive an error.\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" }, "exchangeRate": { "description": "The market exchange rate between this receive-payment'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" }, "paymentMethodId": { "description": "The receive-payment's payment method (e.g., cash, check, credit card).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "memo": { "description": "A memo or note for this receive-payment that will be displayed at the beginning of reports containing details about this receive-payment.", "example": "Payment received at store location - cash", "type": "string" }, "depositToAccountId": { "description": "The account where the funds for this receive-payment will be or have been deposited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditCardTransaction": { "description": "The credit card transaction data for this receive-payment's payment when using QuickBooks Merchant Services (QBMS). If specifying this field, you must also specify the `paymentMethod` field.", "type": "object", "properties": { "request": { "description": "The transaction request data originally supplied for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "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" }, "commercialCardCode": { "description": "The commercial card code identifies the type of business credit card being used (purchase, corporate, or business) for Visa and Mastercard transactions only. When provided, this code may qualify the transaction for lower processing fees compared to the standard rates that apply when no code is specified.", "example": "corporate", "type": "string" }, "transactionMode": { "description": "Indicates whether this credit card transaction came from a card swipe (`card_present`) or not (`card_not_present`).", "example": "card_not_present", "type": "string", "enum": [ "card_not_present", "card_present" ] }, "transactionType": { "description": "The QBMS transaction type from which the current transaction data originated.", "example": "charge", "type": "string", "enum": [ "authorization", "capture", "charge", "refund", "voice_authorization" ] } }, "additionalProperties": false }, "response": { "description": "The transaction response data for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "statusCode": { "description": "The status code returned in the original QBMS transaction response for this credit card transaction.", "example": 0, "type": "number" }, "statusMessage": { "description": "The status message returned in the original QBMS transaction response for this credit card transaction.", "example": "Success", "type": "string" }, "creditCardTransactionId": { "description": "The ID returned from the credit card processor for this credit card transaction.", "example": "1234567890", "type": "string" }, "merchantAccountNumber": { "description": "The QBMS account number of the merchant who is running this transaction using the customer's credit card.", "example": "1234567890", "type": "string" }, "authorizationCode": { "description": "The authorization code returned from the credit card processor to indicate that this charge will be paid by the card issuer.", "example": "1234567890", "type": "string" }, "avsStreetStatus": { "description": "Indicates whether the street address supplied in the transaction request matches the customer's address on file at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "avsZipStatus": { "description": "Indicates whether the customer postal ZIP code supplied in the transaction request matches the customer's postal code recognized at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "cardSecurityCodeMatch": { "description": "Indicates whether the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "reconBatchId": { "description": "An internal ID returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": "1234567890", "type": "string" }, "paymentGroupingCode": { "description": "An internal code returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "paymentStatus": { "description": "Indicates whether this credit card transaction is known to have been successfully processed by the card issuer.", "example": "completed", "type": "string", "enum": [ "completed", "unknown" ] }, "transactionAuthorizedAt": { "description": "The date and time when the credit card processor authorized this credit card transaction.", "example": "2024-01-01 12:34:56 UTC", "type": "string" }, "transactionAuthorizationStamp": { "description": "An internal value for this credit card transaction, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "clientTransactionId": { "description": "A value returned from QBMS transactions for future use by the QuickBooks Reconciliation feature.", "example": "1234567890", "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "applyToTransactions": { "description": "The invoices to be paid by this receive-payment. This will create a link between this receive-payment and the specified invoices.\n\n**IMPORTANT**: In each `applyToTransactions` object, you must specify either `paymentAmount`, `applyCredits`, `discountAmount`, or any combination of these; if none of these are specified, you will receive an error for an empty transaction.\n\n**IMPORTANT**: The target invoice must have `isPaid=false`, otherwise, QuickBooks will report this object as \"cannot be found\".", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "description": "The ID of the target transaction to which this payment is applied.", "example": "123ABC-1234567890" }, "paymentAmount": { "description": "The monetary amount to apply to the target 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": "25.00", "type": "string" }, "applyCredits": { "description": "Credits to apply to this target transaction, reducing its balance. This creates a link between this target transaction 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 target transaction and check the `linkedTransactions` response field. If fetching a list of target transactions, 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 } }, "discountAmount": { "description": "The monetary amount by which to reduce this target transaction's balance, 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": "50.00", "type": "string" }, "discountAccountId": { "description": "The financial account used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "discountClassId": { "description": "The class used to track this target transaction's discount.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "transactionId" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a received payment. When you resubmit applications to invoices, keep them on the same accounts receivable account and include the payment amount, discount, or credit on every allocation you send.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop receive-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the receive-payment to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the receive-payment to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a receive-payment. The deletion will fail if the receive-payment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-orders": { "get": { "summary": "List QuickBooks Desktop sales-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return. Mirror mode: default/max 100. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response. Mirror mode: {\"type\":\"string\",\"maxLength\":12000}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop. Mirror mode: {\"type\":\"string\",\"format\":\"date-time\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound. Mirror mode: {\"type\":\"string\",\"format\":\"date\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion. Mirror mode: {\"type\":\"boolean\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "transactionDate" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "transactionDateBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "isFullyInvoiced", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "isManuallyClosed", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorList" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of sales orders. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "customerId", "contactId", "transactionDateFrom", "transactionDateBefore", "refNumber", "includeLineItems", "isFullyInvoiced", "isManuallyClosed" ] }, "post": { "summary": "Create QuickBooks Desktop sales-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job associated with this sales order.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "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": 36 }, "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": 36 }, "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" } }, "required": [ "customerId", "transactionDate" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedSalesOrdersCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new sales order.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": { "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } } } }, "/api/qbd/v1/sales-orders/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop sales-orders record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "includeLineItems", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorDetail" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a sales order by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific sales orders by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "includeLineItems" ] }, "post": { "summary": "Update QuickBooks Desktop sales-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales order to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales order to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": 36 }, "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": 36 }, "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": 36 }, "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" } }, "required": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedSalesOrdersUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing sales order.\n\n**NOTE:** If you include `lines` or `lineGroups`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": { "contactIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "replaceLineItems": { "type": "boolean" } } }, "delete": { "summary": "Delete QuickBooks Desktop sales-orders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales order to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales order to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a sales order. The deletion will fail if the sales order is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-receipts": { "get": { "summary": "List QuickBooks Desktop sales-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of sales receipts. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop sales-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "description": "The customer or customer-job to which the payment for this sales receipt is credited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The sales receipt'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 receipt'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 receipt when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this sales receipt, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this sales receipt, 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": "RECEIPT-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The sales receipt'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 receipt'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 sales receipt has not been completed.", "example": false, "type": "boolean" }, "checkNumber": { "description": "The check number of a check received for this sales receipt.", "example": "1234567890", "type": "string" }, "paymentMethodId": { "description": "The sales receipt's payment method (e.g., cash, check, credit card).\n\n**NOTE**: If this sales receipt contains credit card transaction data supplied from QuickBooks Merchant Services (QBMS) transaction responses, you must specify a credit card payment method (e.g., \"Visa\", \"MasterCard\", etc.).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this sales receipt must be paid, in ISO 8601 format (YYYY-MM-DD).\n\n**NOTE**: For sales receipts, this field is often `null` because sales receipts are generally used for point-of-sale payments, where full payment is received at the time of purchase.", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The sales receipt's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shippingDate": { "description": "The date when the products or services for this sales receipt 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 receipt, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this sales receipt 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 sales receipt'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 sales receipts, 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 sales receipt that appears in reports, but not on the sales receipt.", "example": "Payment received at store location - cash", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the sales receipt.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this sales receipt is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this sales receipt 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 receipt, 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 }, "depositToAccountId": { "description": "The account where the funds for this sales receipt will be or have been deposited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "creditCardTransaction": { "description": "The credit card transaction data for this sales receipt's payment when using QuickBooks Merchant Services (QBMS). If specifying this field, you must also specify the `paymentMethod` field.", "type": "object", "properties": { "request": { "description": "The transaction request data originally supplied for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "number": { "type": "string", "description": "The credit card number. Must be masked with lower case \"x\" and no dashes.", "example": "xxxxxxxxxxxx1234" }, "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": { "type": "string", "description": "The cardholder's name on the card.", "example": "John Doe" }, "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" }, "commercialCardCode": { "description": "The commercial card code identifies the type of business credit card being used (purchase, corporate, or business) for Visa and Mastercard transactions only. When provided, this code may qualify the transaction for lower processing fees compared to the standard rates that apply when no code is specified.", "example": "corporate", "type": "string" }, "transactionMode": { "description": "Indicates whether this credit card transaction came from a card swipe (`card_present`) or not (`card_not_present`).", "example": "card_not_present", "type": "string", "enum": [ "card_not_present", "card_present" ], "default": "card_not_present" }, "transactionType": { "description": "The QBMS transaction type from which the current transaction data originated.", "example": "charge", "type": "string", "enum": [ "authorization", "capture", "charge", "refund", "voice_authorization" ] } }, "required": [ "number", "expirationMonth", "expirationYear", "name" ], "additionalProperties": false }, "response": { "description": "The transaction response data for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "statusCode": { "description": "The status code returned in the original QBMS transaction response for this credit card transaction.", "example": 0, "type": "number" }, "statusMessage": { "type": "string", "description": "The status message returned in the original QBMS transaction response for this credit card transaction.", "example": "Success" }, "creditCardTransactionId": { "type": "string", "description": "The ID returned from the credit card processor for this credit card transaction.", "example": "1234567890" }, "merchantAccountNumber": { "type": "string", "description": "The QBMS account number of the merchant who is running this transaction using the customer's credit card.", "example": "1234567890" }, "authorizationCode": { "description": "The authorization code returned from the credit card processor to indicate that this charge will be paid by the card issuer.", "example": "1234567890", "type": "string" }, "avsStreetStatus": { "description": "Indicates whether the street address supplied in the transaction request matches the customer's address on file at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "avsZipStatus": { "description": "Indicates whether the customer postal ZIP code supplied in the transaction request matches the customer's postal code recognized at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "cardSecurityCodeMatch": { "description": "Indicates whether the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "reconBatchId": { "description": "An internal ID returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": "1234567890", "type": "string" }, "paymentGroupingCode": { "description": "An internal code returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "paymentStatus": { "description": "Indicates whether this credit card transaction is known to have been successfully processed by the card issuer.", "example": "completed", "type": "string", "enum": [ "completed", "unknown" ] }, "transactionAuthorizedAt": { "type": "string", "description": "The date and time when the credit card processor authorized this credit card transaction.", "example": "2024-01-01 12:34:56 UTC" }, "transactionAuthorizationStamp": { "description": "An internal value for this credit card transaction, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "clientTransactionId": { "description": "A value returned from QBMS transactions for future use by the QuickBooks Reconciliation feature.", "example": "1234567890", "type": "string" } }, "required": [ "statusCode", "statusMessage", "creditCardTransactionId", "merchantAccountNumber", "paymentStatus", "transactionAuthorizedAt" ], "additionalProperties": false } }, "additionalProperties": false }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this sales receipt. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipts 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 receipt'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 receipt's line items, each representing a single product or service sold.\n\n**IMPORTANT**: You must specify `lines`, `lineGroups`, or both when creating a sales receipt.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this sales receipt 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": 36 }, "description": { "description": "A description of this sales receipt line.", "example": "New office chair", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this sales receipt 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 receipt 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 receipt 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 receipt 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 receipt line. This overrides any price level set on the corresponding customer. The resulting sales receipt 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 receipt 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 receipt lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this sales receipt 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 receipt line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this sales receipt 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 receipt line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this sales receipt 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 receipt 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 sales receipt 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 sales receipt 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 sales receipt 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 sales receipt line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipt 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 receipt line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipt 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" }, "creditCardTransaction": { "description": "The credit card transaction data for this sales receipt line's payment when using QuickBooks Merchant Services (QBMS). If specifying this field, you must also specify the `paymentMethod` field.", "type": "object", "properties": { "request": { "description": "The transaction request data originally supplied for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "number": { "type": "string", "description": "The credit card number. Must be masked with lower case \"x\" and no dashes.", "example": "xxxxxxxxxxxx1234" }, "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": { "type": "string", "description": "The cardholder's name on the card.", "example": "John Doe" }, "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" }, "commercialCardCode": { "description": "The commercial card code identifies the type of business credit card being used (purchase, corporate, or business) for Visa and Mastercard transactions only. When provided, this code may qualify the transaction for lower processing fees compared to the standard rates that apply when no code is specified.", "example": "corporate", "type": "string" }, "transactionMode": { "description": "Indicates whether this credit card transaction came from a card swipe (`card_present`) or not (`card_not_present`).", "example": "card_not_present", "type": "string", "enum": [ "card_not_present", "card_present" ], "default": "card_not_present" }, "transactionType": { "description": "The QBMS transaction type from which the current transaction data originated.", "example": "charge", "type": "string", "enum": [ "authorization", "capture", "charge", "refund", "voice_authorization" ] } }, "required": [ "number", "expirationMonth", "expirationYear", "name" ], "additionalProperties": false }, "response": { "description": "The transaction response data for this credit card transaction when using QuickBooks Merchant Services (QBMS).", "type": "object", "properties": { "statusCode": { "description": "The status code returned in the original QBMS transaction response for this credit card transaction.", "example": 0, "type": "number" }, "statusMessage": { "type": "string", "description": "The status message returned in the original QBMS transaction response for this credit card transaction.", "example": "Success" }, "creditCardTransactionId": { "type": "string", "description": "The ID returned from the credit card processor for this credit card transaction.", "example": "1234567890" }, "merchantAccountNumber": { "type": "string", "description": "The QBMS account number of the merchant who is running this transaction using the customer's credit card.", "example": "1234567890" }, "authorizationCode": { "description": "The authorization code returned from the credit card processor to indicate that this charge will be paid by the card issuer.", "example": "1234567890", "type": "string" }, "avsStreetStatus": { "description": "Indicates whether the street address supplied in the transaction request matches the customer's address on file at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "avsZipStatus": { "description": "Indicates whether the customer postal ZIP code supplied in the transaction request matches the customer's postal code recognized at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "cardSecurityCodeMatch": { "description": "Indicates whether the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer.", "example": "pass", "type": "string", "enum": [ "fail", "not_available", "pass" ] }, "reconBatchId": { "description": "An internal ID returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": "1234567890", "type": "string" }, "paymentGroupingCode": { "description": "An internal code returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "paymentStatus": { "description": "Indicates whether this credit card transaction is known to have been successfully processed by the card issuer.", "example": "completed", "type": "string", "enum": [ "completed", "unknown" ] }, "transactionAuthorizedAt": { "type": "string", "description": "The date and time when the credit card processor authorized this credit card transaction.", "example": "2024-01-01 12:34:56 UTC" }, "transactionAuthorizationStamp": { "description": "An internal value for this credit card transaction, needed for the QuickBooks reconciliation feature.", "example": 2, "type": "number" }, "clientTransactionId": { "description": "A value returned from QBMS transactions for future use by the QuickBooks Reconciliation feature.", "example": "1234567890", "type": "string" } }, "required": [ "statusCode", "statusMessage", "creditCardTransactionId", "merchantAccountNumber", "paymentStatus", "transactionAuthorizedAt" ], "additionalProperties": false } }, "additionalProperties": false }, "customFields": { "description": "The custom fields for the sales receipt 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 receipt'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 receipt.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The sales receipt 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": 36 }, "quantity": { "description": "The quantity of the item group associated with this sales receipt 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 receipt 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 sales receipt 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 sales receipt 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 receipt line group is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the sales receipt 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 } } }, "required": [ "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a sales receipt for a sale paid in full. If you include credit card transaction details, QuickBooks requires the payment method to reference a credit card type and automatically deposits the funds to Undeposited Funds rather than a specific bank account.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-receipts/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop sales-receipts record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a sales receipt by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific sales receipts by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop sales-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales receipt to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales receipt to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the sales receipt 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 to which the payment for this sales receipt is credited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The sales receipt'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 receipt'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 receipt when printed or displayed.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this sales receipt, 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 receipt, 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": "RECEIPT-1234", "type": "string", "maxLength": 11 }, "billingAddress": { "description": "The sales receipt'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 receipt'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 sales receipt has not been completed.", "example": false, "type": "boolean" }, "checkNumber": { "description": "The check number of a check received for this sales receipt.", "example": "1234567890", "type": "string" }, "paymentMethodId": { "description": "The sales receipt's payment method (e.g., cash, check, credit card).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "dueDate": { "description": "The date by which this sales receipt must be paid, in ISO 8601 format (YYYY-MM-DD).\n\n**NOTE**: For sales receipts, this field is often `null` because sales receipts are generally used for point-of-sale payments, where full payment is received at the time of purchase.", "example": "2024-10-31", "type": "string", "format": "date" }, "salesRepresentativeId": { "description": "The sales receipt's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shippingDate": { "description": "The date when the products or services for this sales receipt 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 receipt, such as standard mail or overnight delivery.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "shipmentOrigin": { "description": "The origin location from where the product associated with this sales receipt 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 sales receipt'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 sales receipts, 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 sales receipt that appears in reports, but not on the sales receipt.", "example": "Payment received at store location - cash", "type": "string" }, "customerMessageId": { "description": "The message to display to the customer on the sales receipt.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "isQueuedForPrint": { "type": "boolean", "description": "Indicates whether this sales receipt is included in the queue of documents for QuickBooks to print.", "example": true }, "isQueuedForEmail": { "description": "Indicates whether this sales receipt 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 receipt, 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 }, "depositToAccountId": { "description": "The account where the funds for this sales receipt will be or have been deposited.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "otherCustomField": { "description": "A built-in custom field for additional information specific to this sales receipt. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipts 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 receipt'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 receipt'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 sales receipt 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 receipt line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new sales receipt lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this sales receipt 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": 36 }, "description": { "description": "A description of this sales receipt line.", "example": "New office chair", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this sales receipt 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 receipt 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 receipt 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 receipt 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 receipt 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 receipt line. This overrides any price level set on the corresponding customer. The resulting sales receipt 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 receipt 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 receipt lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this sales receipt 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 receipt line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this sales receipt 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 receipt line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this sales receipt 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 receipt 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 sales receipt 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 sales receipt 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 sales receipt 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 sales receipt line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipt 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 receipt line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipt 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 receipt'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 receipt 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 receipt line group you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new sales receipt line groups you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The sales receipt 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": 36 }, "quantity": { "description": "The quantity of the item group associated with this sales receipt 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 receipt 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 receipt 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 receipt 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 sales receipt 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 receipt line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new sales receipt lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this sales receipt 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": 36 }, "description": { "description": "A description of this sales receipt line.", "example": "New office chair", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this sales receipt 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 receipt 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 receipt 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 receipt 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 receipt 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 receipt line. This overrides any price level set on the corresponding customer. The resulting sales receipt 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 receipt 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 receipt lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this sales receipt 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 receipt line.", "example": "base_price", "type": "string", "enum": [ "base_price", "zero" ] }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this sales receipt 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 receipt line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this sales receipt 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 receipt 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 sales receipt 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 sales receipt 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 sales receipt 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 sales receipt line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipt 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 receipt line. Unlike the user-defined fields in the `customFields` array, this is a standard QuickBooks field that exists for all sales receipt 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 } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing sales receipt. Credit card payments still have to use a credit-card payment method and remain deposited to Undeposited Funds, so don’t switch the deposit account in those scenarios.\n\n**NOTE:** If you include `lines` or `lineGroups`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop sales-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales receipt to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales receipt to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a sales receipt. The deletion will fail if the sales receipt is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-representatives": { "get": { "summary": "List QuickBooks Desktop sales-representatives", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of sales representatives.\n\n**NOTE:** QuickBooks Desktop does not support pagination for sales representatives; hence, there is no `cursor` parameter. Users typically have few sales representatives.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop sales-representatives", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initial": { "type": "string", "maxLength": 5, "description": "The initials of this sales representative's name.\n\nMaximum length: 5 characters.", "example": "JD" }, "isActive": { "description": "Indicates whether this sales representative is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "entityId": { "description": "The sales representative's corresponding person entity in QuickBooks, stored as either an employee, vendor, or other-name entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "initial", "entityId" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a sales representative that references an existing employee, vendor, or other-name record so it can be assigned on sales forms.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-representatives/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop sales-representatives record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a sales representative by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific sales representatives by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop sales-representatives", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales representative to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales representative to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the sales representative 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" }, "initial": { "description": "The initials of this sales representative's name.\n\nMaximum length: 5 characters.", "example": "JD", "type": "string", "maxLength": 5 }, "isActive": { "description": "Indicates whether this sales representative is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "entityId": { "description": "The sales representative's corresponding person entity in QuickBooks, stored as either an employee, vendor, or other-name entry.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing sales representative.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-tax-codes": { "get": { "summary": "List QuickBooks Desktop sales-tax-codes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of sales-tax codes.\n\n**NOTE:** QuickBooks Desktop does not support pagination for sales-tax codes; hence, there is no `cursor` parameter. Users typically have few sales-tax codes.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop sales-tax-codes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 3, "description": "The case-insensitive unique name of this sales-tax code, unique across all sales-tax codes. This short name will appear on sales forms to identify the tax status of an item.\n\n**NOTE**: Sales-tax codes 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: 3 characters.", "example": "Tax" }, "isActive": { "description": "Indicates whether this sales-tax code is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "isTaxable": { "type": "boolean", "description": "Indicates whether this sales-tax code is tracking taxable sales. This field cannot be modified once the sales-tax code has been used in a transaction.", "example": true }, "description": { "description": "A description of this sales-tax code.", "example": "Standard tax rate for California", "type": "string" }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this sales-tax code'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 } }, "required": [ "name", "isTaxable" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new sales-tax code.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-tax-codes/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop sales-tax-codes record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a sales-tax code by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific sales-tax codes by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop sales-tax-codes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales-tax code to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales-tax code to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the sales-tax code 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 sales-tax code, unique across all sales-tax codes. This short name will appear on sales forms to identify the tax status of an item.\n\n**NOTE**: Sales-tax codes 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: 3 characters.", "example": "Tax", "type": "string", "maxLength": 3 }, "isActive": { "description": "Indicates whether this sales-tax code is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "isTaxable": { "description": "Indicates whether this sales-tax code is tracking taxable sales. This field cannot be modified once the sales-tax code has been used in a transaction.", "example": true, "type": "boolean" }, "description": { "description": "A description of this sales-tax code.", "example": "Standard tax rate for California", "type": "string" }, "salesTaxItemId": { "description": "The sales-tax item used to calculate the actual tax amount for this sales-tax code'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 } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a sales-tax code’s name, activity status, or linked tax items. Once a code has been used you can’t flip it between taxable and non-taxable, and the built-in TAX/NON codes keep their original taxable setting, so plan new codes if you need a different tax status.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-tax-items": { "get": { "summary": "List QuickBooks Desktop sales-tax-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of sales-tax items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop sales-tax-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this sales-tax item, unique across all sales-tax items.\n\n**NOTE**: Sales-tax items 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": "Standard Tax" }, "barcode": { "description": "The sales-tax 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 sales-tax 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 sales-tax 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 }, "description": { "description": "The sales-tax item's description that will appear on sales forms that include this item.", "example": "Standard rate sales tax for California", "type": "string" }, "taxRate": { "description": "The tax rate defined by this sales-tax item, represented as a decimal string. For example, \"7.5\" represents a 7.5% tax rate. This rate determines the amount of sales tax applied when this item is used in transactions. If a non-zero `taxRate` is specified, then the `taxVendor` field is required.", "example": "7.5", "type": "string" }, "taxVendorId": { "description": "The tax agency (vendor) to whom collected sales taxes are owed for this sales-tax item. This field refers to a vendor in QuickBooks that represents the tax authority. If a non-zero `taxRate` is specified, then `taxVendor` is required.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxReturnLineId": { "description": "The specific line on the sales tax return form where the tax collected using this sales-tax item should be reported.", "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" } }, "required": [ "name" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new sales-tax item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-tax-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop sales-tax-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a sales-tax item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific sales-tax items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop sales-tax-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales-tax item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales-tax item to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the sales-tax 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 unique name of this sales-tax item, unique across all sales-tax items.\n\n**NOTE**: Sales-tax items 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": "Standard Tax", "type": "string", "maxLength": 31 }, "barcode": { "description": "The sales-tax 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 sales-tax item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "classId": { "description": "The sales-tax 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 }, "description": { "description": "The sales-tax item's description that will appear on sales forms that include this item.", "example": "Standard rate sales tax for California", "type": "string" }, "taxRate": { "description": "The tax rate defined by this sales-tax item, represented as a decimal string. For example, \"7.5\" represents a 7.5% tax rate. This rate determines the amount of sales tax applied when this item is used in transactions. If a non-zero `taxRate` is specified, then the `taxVendor` field is required.", "example": "7.5", "type": "string" }, "taxVendorId": { "description": "The tax agency (vendor) to whom collected sales taxes are owed for this sales-tax item. This field refers to a vendor in QuickBooks that represents the tax authority. If a non-zero `taxRate` is specified, then `taxVendor` is required.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxReturnLineId": { "description": "The specific line on the sales tax return form where the tax collected using this sales-tax item should be reported.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing sales-tax item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/service-items": { "get": { "summary": "List QuickBooks Desktop service-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of service items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop service-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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 }, { "$ref": "#/components/schemas/TrackedServiceItemsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new service item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/service-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop service-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a service item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific service items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop service-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the service item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the service item to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": 36 }, "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedServiceItemsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a service item’s details, including its accounts and unit-of-measure set. QuickBooks won’t let you convert a sell-only service into a buy-and-sell service (or the reverse); create a separate item instead. If you’re switching the unit of measure, set `forceUnitOfMeasureChange` so QuickBooks replaces it on existing forms.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/shipping-methods": { "get": { "summary": "List QuickBooks Desktop shipping-methods", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of shipping methods.\n\n**NOTE:** QuickBooks Desktop does not support pagination for shipping methods; hence, there is no `cursor` parameter. Users typically have few shipping methods.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop shipping-methods", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 15, "description": "The case-insensitive unique name of this shipping method, unique across all shipping methods.\n\n**NOTE**: Shipping methods 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: 15 characters.", "example": "FedEx Ground" }, "isActive": { "description": "Indicates whether this shipping method is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new shipping method.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/shipping-methods/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop shipping-methods record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a shipping method by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific shipping methods by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/standard-terms": { "get": { "summary": "List QuickBooks Desktop standard-terms", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of standard terms.\n\n**NOTE:** QuickBooks Desktop does not support pagination for standard terms; hence, there is no `cursor` parameter. Users typically have few standard terms.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop standard-terms", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this standard term, unique across all standard terms.\n\n**NOTE**: Standard terms 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": "Net 30" }, "isActive": { "description": "Indicates whether this standard term is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "dueDays": { "description": "The number of days until payment is due.", "example": 30, "type": "number" }, "discountDays": { "description": "The number of days within which payment must be received to qualify for the discount specified by `discountPercentage`.", "example": 10, "type": "number" }, "discountPercentage": { "description": "The discount percentage applied to the payment if received within the number of days specified by `discountDays`. The value is between 0 and 100.", "example": "10", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new standard term.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/standard-terms/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop standard-terms record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a standard term by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific standard terms by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/subtotal-items": { "get": { "summary": "List QuickBooks Desktop subtotal-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of subtotal items. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop subtotal-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this subtotal item, unique across all subtotal items.\n\n**NOTE**: Subtotal items 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": "Labor subtotal" }, "barcode": { "description": "The subtotal 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 subtotal item 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 subtotal item's description that will appear on sales forms that include this item.", "example": "Subtotal for all labor costs on this project", "type": "string" }, "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 } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new subtotal item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/subtotal-items/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop subtotal-items record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a subtotal item by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific subtotal items by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop subtotal-items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the subtotal item to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the subtotal item to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the subtotal 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 unique name of this subtotal item, unique across all subtotal items.\n\n**NOTE**: Subtotal items 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": "Labor subtotal", "type": "string", "maxLength": 31 }, "barcode": { "description": "The subtotal 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 subtotal item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "type": "boolean" }, "description": { "description": "The subtotal item's description that will appear on sales forms that include this item.", "example": "Subtotal for all labor costs on this project", "type": "string" } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing subtotal item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/templates": { "get": { "summary": "List QuickBooks Desktop templates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of templates. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/time-tracking-activities": { "get": { "summary": "List QuickBooks Desktop time-tracking-activities", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of time tracking activities. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop time-tracking-activities", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionDate": { "type": "string", "format": "date", "description": "The date of this time tracking activity, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "entityId": { "description": "The employee, vendor, or person on QuickBooks's \"Other Names\" list whose time is being tracked in this time tracking activity. This cannot refer to a customer - use the `customer` field to associate a customer or customer-job with this time tracking activity.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customerId": { "description": "The customer or customer-job to which this time tracking activity could be billed. If `billingStatus` is set to \"billable\", this field is required.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serviceItemId": { "description": "The type of service performed during this time tracking activity, referring to billable or purchasable services such as specialized labor, consulting hours, and professional fees.\n\n**NOTE**: This field is not required if no `customer` is specified. However, if `billingStatus` is set to \"billable\", both this field and `customer` are required.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "duration": { "type": "string", "description": "The time spent performing the service during this time tracking activity, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.\n\n**NOTE**: Although seconds can be specified when creating a time tracking activity, they are not returned in responses since QuickBooks Desktop's UI does not display seconds.\n\n**IMPORTANT**: This field is required for updating time tracking activities, even if the field is not being modified, because of a bug in QuickBooks itself.\n\nMust use QuickBooks Desktop's ISO 8601 time interval format (for example, \"PT1H30M\" represents 1 hour and 30 minutes).", "example": "PT1H30M" }, "classId": { "description": "The time tracking activity'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 }, "payrollWageItemId": { "description": "The payroll wage item (e.g., Regular Pay, Overtime Pay) to use for this time tracking activity. This field can only be used for time tracking if: (1) the person specified in `entity` is an employee in QuickBooks, and (2) the \"Use time data to create paychecks\" preference is enabled in their payroll settings.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "note": { "description": "A note or comment about this time tracking activity.", "example": "Project planning meeting with client.", "type": "string" }, "billingStatus": { "description": "The billing status of this time tracking activity.\n\n**IMPORTANT**: When this field is set to \"billable\" for time tracking activities, both `customer` and `serviceItem` are required so that an invoice can be created.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "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": [ "transactionDate", "entityId", "duration" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new time tracking activity.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/time-tracking-activities/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop time-tracking-activities record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a time tracking activity by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific time tracking activities by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop time-tracking-activities", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the time tracking activity to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the time tracking activity to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the time tracking activity 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" }, "transactionDate": { "description": "The date of this time tracking activity, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "entityId": { "description": "The employee, vendor, or person on QuickBooks's \"Other Names\" list whose time is being tracked in this time tracking activity. This cannot refer to a customer - use the `customer` field to associate a customer or customer-job with this time tracking activity.\n\n**IMPORTANT**: This field is required for updating time tracking activities, even if the field is not being modified, because of a bug in QuickBooks itself.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customerId": { "description": "The customer or customer-job to which this time tracking activity could be billed. If `billingStatus` is set to \"billable\", this field is required.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serviceItemId": { "description": "The type of service performed during this time tracking activity, referring to billable or purchasable services such as specialized labor, consulting hours, and professional fees.\n\n**NOTE**: This field is not required if no `customer` is specified. However, if `billingStatus` is set to \"billable\", both this field and `customer` are required.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "duration": { "type": "string", "description": "The time spent performing the service during this time tracking activity, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.\n\n**NOTE**: Although seconds can be specified when creating a time tracking activity, they are not returned in responses since QuickBooks Desktop's UI does not display seconds.\n\n**IMPORTANT**: This field is required for updating time tracking activities, even if the field is not being modified, because of a bug in QuickBooks itself.\n\nMust use QuickBooks Desktop's ISO 8601 time interval format (for example, \"PT1H30M\" represents 1 hour and 30 minutes).", "example": "PT1H30M" }, "classId": { "description": "The time tracking activity'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 }, "payrollWageItemId": { "description": "The payroll wage item (e.g., Regular Pay, Overtime Pay) to use for this time tracking activity. This field can only be used for time tracking if: (1) the person specified in `entity` is an employee in QuickBooks, and (2) the \"Use time data to create paychecks\" preference is enabled in their payroll settings.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "note": { "description": "A note or comment about this time tracking activity.", "example": "Project planning meeting with client.", "type": "string" }, "billingStatus": { "description": "The billing status of this time tracking activity.\n\n**IMPORTANT**: When this field is set to \"billable\" for time tracking activities, both `customer` and `serviceItem` are required so that an invoice can be created.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] } }, "required": [ "revisionNumber", "entityId", "duration" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing time tracking activity.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop time-tracking-activities", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the time tracking activity to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the time tracking activity to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a time tracking activity. The deletion will fail if the time tracking activity is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/transactions": { "get": { "summary": "List QuickBooks Desktop transactions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Searches across all transaction types. Unlike transaction-specific queries, this endpoint only returns fields common to all transaction types, such as ID, type, dates, account, and reference numbers. For more details specific to that transaction type, make a subsequent call to the relevant transaction-specific endpoint (such as invoices, bills, etc.). NOTE: This endpoint does not support time tracking activities. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/transactions/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop transactions record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a transaction by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific transactions by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/transfers": { "get": { "summary": "List QuickBooks Desktop transfers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of transfers. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop transfers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionDate": { "type": "string", "format": "date", "description": "The date of this transfer, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "sourceAccountId": { "description": "The account from which money will be transferred.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "targetAccountId": { "description": "The account to which money will be transferred.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The transfer'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 }, "amount": { "type": "string", "description": "The monetary amount of this transfer, 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": "1000.00" }, "memo": { "description": "A memo or note for this transfer.", "example": "Monthly transfer to savings", "type": "string" } }, "required": [ "transactionDate", "sourceAccountId", "targetAccountId", "amount" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new transfer.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/transfers/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop transfers record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a transfer by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific transfers by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop transfers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the transfer to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the transfer to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the transfer 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" }, "transactionDate": { "description": "The date of this transfer, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01", "type": "string", "format": "date" }, "sourceAccountId": { "description": "The account from which money will be transferred.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "targetAccountId": { "description": "The account to which money will be transferred.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The transfer'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 }, "amount": { "description": "The monetary amount of this transfer, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this transfer.", "example": "Monthly transfer to savings", "type": "string" } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing transfer.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/unit-of-measure-sets": { "get": { "summary": "List QuickBooks Desktop unit-of-measure-sets", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists all unit-of-measure sets. NOTE: QuickBooks Desktop does not support pagination for unit-of-measure sets; hence, there is no cursor parameter. Users typically have few unit-of-measure sets.\n\nNOTE: The QuickBooks company file must have unit-of-measure enabled (either a single unit per item or multiple units per item).\n\n**NOTE:** QuickBooks Desktop does not support pagination for unit-of-measure sets; hence, there is no `cursor` parameter. Users typically have few unit-of-measure sets.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop unit-of-measure-sets", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this unit-of-measure set, unique across all unit-of-measure sets. To ensure this set appears in the QuickBooks UI for companies configured with a single unit per item, prefix the name with \"By the\" (e.g., \"By the Barrel\").\n\n**NOTE**: Unit-of-measure sets 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": "Weight Units" }, "isActive": { "description": "Indicates whether this unit-of-measure set is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.", "example": true, "default": true, "type": "boolean" }, "unitOfMeasureType": { "description": "The unit-of-measure set's type. Use \"other\" for a custom type defined in QuickBooks.", "example": "count", "type": "string", "enum": [ "area", "count", "length", "other", "time", "volume", "weight" ] }, "baseUnit": { "description": "The unit-of-measure set's base unit used to track and price item quantities. If the company file is enabled for a single unit of measure per item, the base unit is the only unit available on transaction line items. If enabled for multiple units per item, the base unit is the default unless overridden by the set's default units.", "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this base unit, unique across all base units.\n\n**NOTE**: Base units 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": "Each" }, "abbreviation": { "type": "string", "maxLength": 31, "description": "The base unit's short identifier shown in the QuickBooks U/M field on transaction line items.\n\nMaximum length: 31 characters.", "example": "ea" } }, "required": [ "name", "abbreviation" ], "additionalProperties": false }, "relatedUnits": { "description": "The unit-of-measure set's related units, each specifying how many base units they represent (conversion ratio).", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 31, "description": "The case-insensitive unique name of this related unit, unique across all related units.\n\n**NOTE**: Related units 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": "Case" }, "abbreviation": { "type": "string", "maxLength": 31, "description": "The related unit's short identifier shown in the QuickBooks U/M field on transaction line items.\n\nMaximum length: 31 characters.", "example": "ea" }, "conversionRatio": { "type": "string", "description": "The number of base units in this related unit, represented as a decimal string. For example, if the base unit is \"box\" and this related unit is \"case\" with `conversionRatio` = \"10\", that means there are 10 boxes in one case.", "example": "10" } }, "required": [ "name", "abbreviation", "conversionRatio" ], "additionalProperties": false } }, "defaultUnits": { "description": "The unit-of-measure set's default units to appear in the U/M field on transaction line items. You can specify separate defaults for purchases, sales, and shipping.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "unitUsedFor": { "description": "Where this default unit is used as the default: purchase line items, sales line items, or shipping lines.", "example": "purchase", "type": "string", "enum": [ "purchase", "sales", "shipping" ] }, "unit": { "type": "string", "maxLength": 31, "description": "The unit name for this default unit, as displayed in the U/M field. If the company file is enabled for multiple units per item, this appears as an available unit for the item. Must correspond to the base unit or a related unit defined in this set.\n\nMaximum length: 31 characters.", "example": "Each" } }, "required": [ "unitUsedFor", "unit" ], "additionalProperties": false } } }, "required": [ "name", "unitOfMeasureType", "baseUnit" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new unit-of-measure set.\n\nNOTE: The QuickBooks company file must have unit-of-measure enabled (either a single unit per item or multiple units per item). To support both configurations, prefix all UOM set names with \"By the\" (for example, \"By the Barrel\"); otherwise, the set may not appear in the QuickBooks UI when the company file is configured for a single unit per item.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/unit-of-measure-sets/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop unit-of-measure-sets record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves an unit-of-measure set by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific unit-of-measure sets by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/vendor-credits": { "get": { "summary": "List QuickBooks Desktop vendor-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, "required": false, "name": "refNumbers", "in": "query", "description": "Filters transactions to specific QuickBooks Desktop reference numbers." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date lower bound." }, "required": false, "name": "transactionDateFrom", "in": "query", "description": "Inclusive transaction-date lower bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive transaction-date upper bound." }, "required": false, "name": "transactionDateTo", "in": "query", "description": "Inclusive transaction-date upper bound." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters transactions by QuickBooks Desktop reference number text." }, "required": false, "name": "refNumber", "in": "query", "description": "Filters transactions by QuickBooks Desktop reference number text." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "refNumberMatchMode", "in": "query", "description": "Controls how the `refNumber` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, "required": false, "name": "refNumberTo", "in": "query", "description": "Upper bound for QuickBooks Desktop reference-number range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, "required": false, "name": "entityIds", "in": "query", "description": "Filters transactions by related QuickBooks Desktop entity IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related customer or customer-job IDs." }, "required": false, "name": "customerIds", "in": "query", "description": "Filters transactions by related customer or customer-job IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related vendor IDs." }, "required": false, "name": "vendorIds", "in": "query", "description": "Filters transactions by related vendor IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related account IDs." }, "required": false, "name": "accountIds", "in": "query", "description": "Filters transactions by related account IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters transactions by related item IDs." }, "required": false, "name": "itemIds", "in": "query", "description": "Filters transactions by related item IDs." }, { "schema": { "type": "boolean", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, "required": false, "name": "includeLineItems", "in": "query", "description": "When true, includes transaction line-item detail when the resource supports line expansion." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of vendor credits. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create QuickBooks Desktop vendor-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "description": "The vendor who sent this vendor credit for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this vendor credit is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this vendor credit is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "type": "string", "format": "date", "description": "The date of this vendor credit, in ISO 8601 format (YYYY-MM-DD).", "example": "2024-10-01" }, "refNumber": { "description": "The case-sensitive user-defined reference number for this vendor credit, 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: 20 characters.", "example": "VCREDIT-1234", "type": "string", "maxLength": 20 }, "memo": { "description": "A memo or note for this vendor credit.", "example": "Credit for returned merchandise - Invoice INV-1234", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this vendor credit, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the vendor credit's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this vendor credit'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" }, "expenseLines": { "description": "The vendor credit's expense lines, each representing one line in this expense.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the expense 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 } }, "itemLines": { "description": "The vendor credit's item lines, each representing the purchase of a specific item or service.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item line. Must be a valid unit within the item's available units of measure.", "example": "Each", "type": "string" }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ], "default": "billable" }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "linkToTransactionLine": { "description": "An existing transaction line that you wish to link to this item 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. If the parent transaction is a bill or an item receipt, you can only link to purchase orders; QuickBooks does not support linking these transactions to other transaction types.\n\nTransaction lines can only be linked when creating this item line and cannot be unlinked later.\n\n**IMPORTANT**: If you use `linkToTransactionLine` on this item 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 item 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 transaction and check the `linkedTransactions` response field. If fetching a list of transactions, you must also specify the parameter `includeLinkedTransactions=true` to see the `linkedTransactions` response field.", "type": "object", "properties": { "transactionId": { "type": "string", "maxLength": 36, "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 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item 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 } }, "itemGroupLines": { "description": "The vendor credit's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "inventorySiteId": { "description": "The site location where inventory for the item group associated with this item group 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 group associated with this item group line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "customFields": { "description": "The custom fields for the item group 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 } } }, "required": [ "itemGroupId" ], "additionalProperties": false } } }, "required": [ "vendorId", "transactionDate" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a vendor credit to capture returns, rebates, or other amounts a vendor owes so you can apply the credit when recording future bill payments.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/vendor-credits/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop vendor-credits record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a vendor credit by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific vendor credits by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\nNOTE: The response automatically includes any linked transactions.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Update QuickBooks Desktop vendor-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the vendor credit to update.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the vendor credit to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionNumber": { "type": "string", "description": "The current QuickBooks-assigned revision number of the vendor credit 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" }, "vendorId": { "description": "The vendor who sent this vendor credit for goods or services purchased.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "payablesAccountId": { "description": "The Accounts-Payable (A/P) account to which this vendor credit is assigned, used for accounts-payable tracking. If omitted, QuickBooks Desktop uses the default A/P account configured in the company file.\n\n**IMPORTANT**: If this vendor credit is linked to other transactions, this A/P account must match the `payablesAccount` used in those other transactions.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "transactionDate": { "description": "The date of this vendor credit, 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 vendor credit, 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: 20 characters.", "example": "VCREDIT-1234", "type": "string", "maxLength": 20 }, "memo": { "description": "A memo or note for this vendor credit.", "example": "Credit for returned merchandise - Invoice INV-1234", "type": "string" }, "salesTaxCodeId": { "description": "The sales-tax code for this vendor credit, determining whether it is taxable or non-taxable. If set, this overrides any sales-tax codes defined on the vendor. This can be overridden on the vendor credit's individual lines.\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 }, "exchangeRate": { "description": "The market exchange rate between this vendor credit'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" }, "clearExpenseLines": { "description": "When `true`, removes all existing expense lines associated with this vendor credit. To modify or add individual expense lines, use the field `expenseLines` instead.", "example": false, "type": "boolean" }, "expenseLines": { "description": "The vendor credit's expense lines, each representing one line in this expense.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing expense lines for the vendor credit with this array. To keep any existing expense lines, you must include them in this array even if they have not changed. **Any expense lines not included will be removed.**\n\n2. To add a new expense line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any expense lines, 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 expense line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new expense lines you wish to add.", "example": "456DEF-1234567890" }, "accountId": { "description": "The expense account being debited (increased) for this expense line. The corresponding account being credited is usually a liability account (e.g., Accounts-Payable) or an asset account (e.g., Cash), depending on the transaction type.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "amount": { "description": "The monetary amount of this expense line, 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": "1000.00", "type": "string" }, "memo": { "description": "A memo or note for this expense line.", "example": "New office chair", "type": "string" }, "payeeId": { "description": "If `account` refers to an Accounts-Payable (A/P) account, `payee` refers to the expense's vendor (not the customer). If `account` refers to any other type of account, `payee` refers to the expense's customer (not the vendor).", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The expense 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 expense lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this expense 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 }, "billingStatus": { "description": "The billing status of this expense line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "salesRepresentativeId": { "description": "The expense line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "clearItemLines": { "description": "When `true`, removes all existing item lines associated with this vendor credit. To modify or add individual item lines, use the field `itemLines` instead.", "example": false, "type": "boolean" }, "itemLines": { "description": "The vendor credit's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the vendor credit with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } }, "itemGroupLines": { "description": "The vendor credit's item group lines, each representing a predefined set of items bundled together because they are commonly purchased together or grouped for faster entry.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item group lines for the vendor credit with this array. To keep any existing item group lines, you must include them in this array even if they have not changed. **Any item group lines not included will be removed.**\n\n2. To add a new item group line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item group lines, 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 item group line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item group lines you wish to add.", "example": "456DEF-1234567890" }, "itemGroupId": { "description": "The item group line'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": 36 }, "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" }, "overrideUnitOfMeasureSetId": { "description": "Specifies an alternative unit-of-measure set when updating this item group 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 }, "itemLines": { "description": "The item group line's item lines, each representing the purchase of a specific item or service.\n\n**IMPORTANT**:\n\n1. Including this array in your update request will **REPLACE** all existing item lines for the item group line with this array. To keep any existing item lines, you must include them in this array even if they have not changed. **Any item lines not included will be removed.**\n\n2. To add a new item line, include it here with the `id` field set to `-1`.\n\n3. If you do not wish to modify any item lines, 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 item line you wish to retain or update.\n\n**IMPORTANT**: Set this field to `-1` for new item lines you wish to add.", "example": "456DEF-1234567890" }, "itemId": { "description": "The item associated with this item 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": 36 }, "inventorySiteId": { "description": "The site location where inventory for the item associated with this item 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 item line is stored.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "serialNumber": { "description": "The serial number of the item associated with this item 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 item line. Used for tracking groups of inventory items that are purchased or manufactured together.", "example": "LOT2023-001", "type": "string" }, "expirationDate": { "description": "The expiration date for the serial number or lot number of the item associated with this item line, in ISO 8601 format (YYYY-MM-DD). This is particularly relevant for perishable or time-sensitive inventory items. Note that this field is only supported on QuickBooks Desktop 2023 or later.", "example": "2025-12-31", "type": "string", "format": "date" }, "description": { "description": "A description of this item line.", "example": "High-quality widget with custom engraving", "type": "string" }, "quantity": { "description": "The quantity of the item associated with this 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" }, "unitOfMeasure": { "description": "The unit-of-measure used for the `quantity` in this item 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 item 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 }, "cost": { "description": "The cost of this item line, represented as a decimal string. If both `quantity` and `amount` are specified but not `cost`, QuickBooks will use them to calculate `cost`.\n\nDecimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, \"123.45\").", "example": "1000.00", "type": "string" }, "amount": { "description": "The monetary amount of this item line, represented as a decimal string. If both `quantity` and `cost` are specified but not `amount`, QuickBooks will use them to calculate `amount`. If `amount`, `cost`, and `quantity` are all unspecified, then QuickBooks will calculate `amount` based on a `quantity` of `1` and the suggested `cost`. 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" }, "customerId": { "description": "The customer or customer-job associated with this item line.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "classId": { "description": "The item 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 item lines unless overridden here, at the transaction line level.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesTaxCodeId": { "description": "The sales-tax code for this item 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 }, "billingStatus": { "description": "The billing status of this item line.", "example": "billable", "type": "string", "enum": [ "billable", "has_been_billed", "not_billable" ] }, "overrideItemAccountId": { "description": "The account to use for this item line, overriding the default account associated with the item.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 }, "salesRepresentativeId": { "description": "The item line's sales representative. Sales representatives can be employees, vendors, or other names in QuickBooks.", "example": "80000001-1234567890", "type": "string", "maxLength": 36 } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "revisionNumber" ], "additionalProperties": false } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates a vendor credit before you apply it to bills, letting you adjust the amounts, memo, or line allocations that make up the credit.\n\n**NOTE:** If you include `expenseLines`, `itemLines`, or `itemGroupLines`, QuickBooks Desktop replaces each included line list with the array you send, so include unchanged lines you want to keep and use `id: \"-1\"` for new lines.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] }, "delete": { "summary": "Delete QuickBooks Desktop vendor-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the vendor credit to delete.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the vendor credit to delete." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Permanently deletes a a vendor credit. The deletion will fail if the vendor credit is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/vendors": { "get": { "summary": "List QuickBooks Desktop vendors", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return. Mirror mode: default/max 100. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response. Mirror mode: {\"type\":\"string\",\"maxLength\":12000}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "transaction_date", "updated_at" ], "description": "QuickBooks Desktop date field used by the date range filters." }, "required": false, "name": "dateField", "in": "query", "description": "QuickBooks Desktop date field used by the date range filters." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateFrom", "in": "query", "description": "Inclusive start date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, "required": false, "name": "dateTo", "in": "query", "description": "Inclusive end date or date-time for the selected QuickBooks Desktop date field." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop. Mirror mode: {\"type\":\"string\",\"format\":\"date-time\"}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters list records by QuickBooks Desktop name." }, "required": false, "name": "name", "in": "query", "description": "Filters list records by QuickBooks Desktop name." }, { "schema": { "type": "string", "enum": [ "contains", "starts_with", "ends_with" ], "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, "required": false, "name": "nameMatchMode", "in": "query", "description": "Controls how the `name` filter is matched, such as exact, contains, starts with, or ends with." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "name" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdApiCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorList" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a list of vendors. Use the `cursor` parameter to paginate through the results.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "active", "email" ] }, "post": { "summary": "Create QuickBooks Desktop vendors", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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 }, { "$ref": "#/components/schemas/TrackedVendorsCreate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new vendor.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/vendors/{id}": { "get": { "summary": "Retrieve a QuickBooks Desktop vendors record", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, "required": true, "name": "id", "in": "path", "description": "The QuickBooks Desktop record ID for the resource being retrieved, updated, deleted, or voided." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup. Mirror mode: {\"type\":\"string\",\"enum\":[\"mirror\",\"mirror_then_refresh\"]}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure. Mirror mode: {\"type\":\"string\",\"minLength\":1,\"maxLength\":512}. Other native filters are not valid in mirror mode." }, { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." }, "required": true, "name": "x-boost-qbd-connection-id", "in": "header", "description": "The Boost Connect QBD connection ID that identifies which QuickBooks Desktop company file should handle this request." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogSnapshotDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] }, { "$ref": "#/components/schemas/ResourceMirrorDetail" } ] } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieves a vendor by ID.\n\n**IMPORTANT:** If you need to fetch multiple specific vendors by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-required-permissions": [ "qbd:read" ], "x-mirror-query-parameters": [ "readMode", "afterOperationId" ] }, "post": { "summary": "Update QuickBooks Desktop vendors", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the vendor to update.", "example": "80000001-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the vendor to update." }, { "name": "writeMode", "in": "query", "schema": { "type": "string", "enum": [ "tracked" ] }, "description": "Choose connector-owned pending records and dependencies." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "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": [ "revisionNumber" ], "additionalProperties": false }, { "$ref": "#/components/schemas/TrackedVendorsUpdate" } ] } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the request. Tracked idempotent replay: already confirmed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "202": { "description": "Tracked: accepted and readable immediately, not yet written to QuickBooks. Direct: native operation acceptance.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "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": "Revision/idempotency conflict, failed/overdue dependency, wrong company, or mirror unavailable for writes." }, "422": { "description": "QuickBooks rejected the request. Tracked idempotent replay: explicitly failed; inspect the mirror sync.error.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdWriteResultDto" }, { "$ref": "#/components/schemas/PendingWriteReceipt" } ] } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Updates an existing vendor.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.\n\nTracked writes require writeMode=tracked, an enabled mirror, and an Idempotency-Key header. Acceptance durably saves a readable/searchable pending record before returning 202. An identical retry reuses the record/write identity; a changed body with the same key returns 409. Keep the key until the response is recovered. No direct-write fallback occurs. Without tracked mode the separate direct/QBXML operation API does not promise optimistic mirror records.\n\nThe connector serializes updates and resolves pending customer/job/product references before dispatch. A first update to a confirmed record requires its revisionNumber. Edits queued behind this connector's own edits use the preceding confirmed revision, not an arbitrary latest revision. A 15-minute deadline marks needs_attention; it never deletes records or blindly retries unknown accounting outcomes. Mirror GET/list/search returns sync.status. Applications may use signed mirror.record.updated webhooks and reread the record; operation polling is unnecessary.\n\nFor invoices, estimates and sales orders, contactIds (maximum 20) optionally associates owner-scoped contact IDs belonging to the exact CustomerRef customer/job. Email alone is not an identity. Pending contacts may be linked; failed/needs_attention contacts are rejected at acceptance. These optional links never delay or fail the accounting document when the required customer/job is ready. Get the contacts separately for their own sync status. The contact IDs are stored only by the connector and never sent as QBXML.\n\nDocument line edits have QuickBooks replacement semantics: include every retained line. Set replaceLineItems=true to acknowledge this; every update line requires id/TxnLineID (use -1 explicitly for a new line). Header-only edits do not replace lines. Native IDs for lines of a pending new document are unavailable until confirmation; use header edits meanwhile. No automatic conversion of an estimate to a sales order is implied. Copy desired data explicitly; native invoice-to-sales-order references support connector IDs through linkToTransactionIds.\n\nSee docs/architecture/pending-resource-writes.md and docs/architecture/pending-writes-monday-handoff.md.", "x-required-permissions": [ "qbd:write" ], "x-tracked-write": true, "x-tracked-body-properties": {} } }, "/api/qbd/v1/bill-check-payments/{id}/void": { "post": { "summary": "Void QuickBooks Desktop bill-check-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill check payment to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill check payment to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a bill check payment by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the bill check payment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bill-credit-card-payments/{id}/void": { "post": { "summary": "Void QuickBooks Desktop bill-credit-card-payments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill credit card payment to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill credit card payment to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a bill credit card payment by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the bill credit card payment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/bills/{id}/void": { "post": { "summary": "Void QuickBooks Desktop bills", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the bill to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the bill to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a bill by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the bill is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/checks/{id}/void": { "post": { "summary": "Void QuickBooks Desktop checks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the check to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the check to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a check by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the check is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-charges/{id}/void": { "post": { "summary": "Void QuickBooks Desktop credit-card-charges", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card charge to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card charge to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a credit card charge by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the credit card charge is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-credits/{id}/void": { "post": { "summary": "Void QuickBooks Desktop credit-card-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card credit to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card credit to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a credit card credit by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the credit card credit is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-card-refunds/{id}/void": { "post": { "summary": "Void QuickBooks Desktop credit-card-refunds", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit card refund to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit card refund to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a credit card refund by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the credit card refund is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/credit-memos/{id}/void": { "post": { "summary": "Void QuickBooks Desktop credit-memos", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the credit memo to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the credit memo to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a credit memo by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the credit memo is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/deposits/{id}/void": { "post": { "summary": "Void QuickBooks Desktop deposits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the deposit to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the deposit to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a deposit by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the deposit is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/inventory-adjustments/{id}/void": { "post": { "summary": "Void QuickBooks Desktop inventory-adjustments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the inventory adjustment to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the inventory adjustment to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids an inventory adjustment by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the inventory adjustment is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/invoices/{id}/void": { "post": { "summary": "Void QuickBooks Desktop invoices", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the invoice to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the invoice to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids an invoice by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the invoice is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/item-receipts/{id}/void": { "post": { "summary": "Void QuickBooks Desktop item-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the item receipt to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the item receipt to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids an item receipt by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the item receipt is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/journal-entries/{id}/void": { "post": { "summary": "Void QuickBooks Desktop journal-entries", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the journal entry to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the journal entry to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a journal entry by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the journal entry is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/sales-receipts/{id}/void": { "post": { "summary": "Void QuickBooks Desktop sales-receipts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the sales receipt to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the sales receipt to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a sales receipt by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the sales receipt is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/vendor-credits/{id}/void": { "post": { "summary": "Void QuickBooks Desktop vendor-credits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "x-boost-qbd-connection-id", "schema": { "type": "string", "description": "The Boost Connect QBD connection ID for this request.", "example": "connection-1", "x-stainless-naming": { "typescript": { "method_argument": "qbdConnectionId" }, "mcp": { "method_argument": "qbdConnectionId" } } }, "required": true, "description": "The Boost Connect QBD connection ID for this request." }, { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 36, "description": "The QuickBooks-assigned unique identifier of the vendor credit to void.", "example": "123ABC-1234567890" }, "required": true, "description": "The QuickBooks-assigned unique identifier of the vendor credit to void." } ], "responses": { "200": { "description": "QuickBooks accepted the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks request is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Voids a vendor credit by setting its amount to zero while keeping a record of it in QuickBooks. The void will fail if the vendor credit is currently in use or has any linked transactions that are in use.\n\n**Requirements:**\n- Requires a public API bearer key.\n- Requires the `x-boost-qbd-connection-id` header with the target Boost Connect QBD connection ID.\n- Connection must be active, QuickBooks Web Connector must be running, and the intended company file must be available.\n- Write operations depend on QuickBooks Desktop accepting the translated qbXML request; updates usually require the latest QuickBooks revision/edit sequence field when the request schema includes one.\n- Use `completionMode=wait` to wait for a result when possible or async processing when clients can poll operation state later.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/connections/{id}/qwc": { "get": { "summary": "Download QuickBooks Web Connector configuration", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/x-qwc": { "schema": { "type": "string" } } } }, "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": "Downloads the QWC configuration file for an existing connection. Import this file into QuickBooks Web Connector on the desktop running the target QuickBooks company file.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- Requires an existing connection; downloaded QWC files must be imported into QuickBooks Web Connector.", "x-required-permissions": [ "setup:create" ] } }, "/api/qbd/v1/connections/{id}/qwc-password": { "post": { "summary": "Reset QuickBooks Web Connector password", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdConnectionPasswordResetDto" } } } }, "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": "Resets the Web Connector password for an existing connection and returns the new password once. Update QuickBooks Web Connector with the new password before expecting check-ins to resume.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- Requires an existing connection; downloaded QWC files must be imported into QuickBooks Web Connector.", "x-required-permissions": [ "setup:create" ] } }, "/api/qbd/v1/connections/{id}/qwc-file": { "post": { "summary": "Reset QuickBooks Web Connector file identity", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdConnectionQwcFileResetDto" } } } }, "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": "Rotates the QWC file identity for an existing connection and returns a new QWC download URL. Use this when QuickBooks Web Connector registration is stuck on an old OwnerID, FileID, or app identity.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- Requires an existing connection; downloaded QWC files must be imported into QuickBooks Web Connector.", "x-required-permissions": [ "setup:create" ] } }, "/api/qbd/v1/connections/{id}/company-identity/override": { "post": { "summary": "Accept detected QuickBooks company file", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverrideQbdCompanyIdentityRequestDto" } } }, "description": "JSON request payload for this operation." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdCompanyIdentityOverrideDto" } } } }, "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": "Accepts the detected QuickBooks Desktop company file for an existing connection after a company identity mismatch. The detected fingerprint must match the stored mismatch candidate; otherwise the request is rejected.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "connections:write" ] } }, "/api/qbd/v1/connections/{id}/setup-session": { "post": { "summary": "Create hosted setup session", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQbdSetupSessionRequestDto" } } }, "description": "JSON request payload for this operation." }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdSetupSessionCreatedDto" } } } }, "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 hosted setup session for an existing connection. The session lets a customer open setup, download the QWC file, copy or reset the Web Connector password, and complete callback redirect flow without direct API access.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "setup:create" ] }, "get": { "summary": "Read active hosted setup session for connection", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdSetupSessionConnectionViewDto" } } } }, "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 the active hosted setup session for a connection. Use it to resume setup, display current setup state, or decide whether a new hosted setup link is needed.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "setup:create" ] } }, "/api/qbd/v1/connections/{id}/operations": { "get": { "summary": "List connection operations", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/QbdOperationDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 } }, "required": [ "operations", "nextKey", "remainingCount" ] } } } }, "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 queued and completed operations for one QuickBooks Desktop connection. Use this for support, diagnostics, and progress tracking when live reads or writes are waiting on Web Connector.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Queue raw qbXML operation", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQbdOperationRequestDto" } } }, "description": "JSON request payload for this operation." }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/QbdOperationDto" } }, "required": [ "operation" ] } } } }, "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" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Queues a raw qbXML operation for one connection. This is an escape hatch for trusted internal flows that need to send qbXML directly rather than using the typed public resource routes.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/connections/{id}/operations/{operationId}": { "get": { "summary": "Read connection operation", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "string", "minLength": 1, "description": "The queued QuickBooks Desktop operation ID." }, "required": true, "name": "operationId", "in": "path", "description": "The queued QuickBooks Desktop operation ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/QbdOperationDto" } }, "required": [ "operation" ] } } } }, "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 queued operation and its QuickBooks response state. Use it to diagnose failures, retry decisions, status codes, and Web Connector processing progress.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/catalog-refreshes/{refreshId}": { "get": { "summary": "Read catalog refresh status", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "string", "minLength": 1, "description": "The materialized QuickBooks Desktop catalog refresh ID returned by a 202 response." }, "required": true, "name": "refreshId", "in": "path", "description": "The materialized QuickBooks Desktop catalog refresh ID returned by a 202 response." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh": { "$ref": "#/components/schemas/QbdCatalogRefreshDto" } }, "required": [ "refresh" ] } } } }, "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 materialized QuickBooks Desktop catalog refresh. Poll this endpoint after a read returns 202 Accepted.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/search/contacts": { "get": { "summary": "Search mirrored contacts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "string", "maxLength": 200, "description": "Normalized case-insensitive token prefixes for a compact mirrored contact/product lookup; up to eight tokens." }, "required": false, "name": "q", "in": "query", "description": "Normalized case-insensitive token prefixes for a compact mirrored contact/product lookup; up to eight tokens." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "default": "active", "description": "Selects active, inactive, or all mirrored lookup records." }, "required": false, "name": "active", "in": "query", "description": "Selects active, inactive, or all mirrored lookup records." } ], "responses": { "200": { "description": "Compact prefix/token lookup results; no live QBWC fallback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdSearchResponse" } } } }, "202": { "description": "The initial Firestore-backed index is still building.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdSearchResponse" } } } }, "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 mirror or lookup resource is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "503": { "description": "Search is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } } }, "description": "Search mirrored contacts.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/search/products": { "get": { "summary": "Search mirrored products", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "string", "maxLength": 200, "description": "Normalized case-insensitive token prefixes for a compact mirrored contact/product lookup; up to eight tokens." }, "required": false, "name": "q", "in": "query", "description": "Normalized case-insensitive token prefixes for a compact mirrored contact/product lookup; up to eight tokens." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "default": "active", "description": "Selects active, inactive, or all mirrored lookup records." }, "required": false, "name": "active", "in": "query", "description": "Selects active, inactive, or all mirrored lookup records." } ], "responses": { "200": { "description": "Compact prefix/token lookup results; no live QBWC fallback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdSearchResponse" } } } }, "202": { "description": "The initial Firestore-backed index is still building.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdSearchResponse" } } } }, "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 mirror or lookup resource is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "503": { "description": "Search is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } } }, "description": "Search mirrored products.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/usage": { "get": { "summary": "Read connection API usage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "$ref": "#/components/schemas/QbdConnectionUsageSummaryDto" } }, "required": [ "usage" ] } } } }, "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 approximate Analytics Engine usage for one connection and merges it with current queue and polling state from the connection runtime.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "diagnostics:read" ] } }, "/api/qbd/v1/connections/{id}/catalog/{entityType}": { "get": { "summary": "Query live catalog snapshots", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "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" ], "description": "The QuickBooks Desktop catalog entity type to read from stored snapshots." }, "required": true, "name": "entityType", "in": "path", "description": "The QuickBooks Desktop catalog entity type to read from stored snapshots." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCatalogListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Queries stored live catalog snapshots for one connection and entity type. Use this lower-level route when a typed public resource projection is not available or support needs raw synced data.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- QuickBooks Web Connector must be able to check in for live QuickBooks Desktop reads or writes to complete.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/customers": { "get": { "summary": "List live QuickBooks Desktop customers and jobs", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, "required": false, "name": "ids", "in": "query", "description": "Filters to specific QuickBooks Desktop record IDs. When supplied, QuickBooks may ignore other filters for the same request." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, "required": false, "name": "fullNames", "in": "query", "description": "Filters to specific QuickBooks Desktop full names. Hierarchical resources use colon-delimited full names such as Parent:Child." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 150, "default": 150, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous public API list response." }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous public API list response." }, { "schema": { "type": "string", "enum": [ "active", "inactive", "all" ], "default": "active", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, "required": false, "name": "status", "in": "query", "description": "Filters active, inactive, or all QuickBooks Desktop list records." }, { "schema": { "type": "string", "enum": [ "name", "full_name", "updated_at", "transaction_date", "ref_number", "total_amount" ], "description": "Field used to order returned records when the resource supports sorting." }, "required": false, "name": "sortBy", "in": "query", "description": "Field used to order returned records when the resource supports sorting." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for returned records." }, "required": false, "name": "sortDirection", "in": "query", "description": "Sort order for returned records." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedAfter", "in": "query", "description": "Filters records updated at or after this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, "required": false, "name": "updatedBefore", "in": "query", "description": "Filters records updated at or before this date or date-time in QuickBooks Desktop." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs whose QuickBooks Desktop name contains this text." }, "required": false, "name": "nameContains", "in": "query", "description": "Filters customers or jobs whose QuickBooks Desktop name contains this text." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs whose QuickBooks Desktop name starts with this text." }, "required": false, "name": "nameStartsWith", "in": "query", "description": "Filters customers or jobs whose QuickBooks Desktop name starts with this text." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs whose QuickBooks Desktop name ends with this text." }, "required": false, "name": "nameEndsWith", "in": "query", "description": "Filters customers or jobs whose QuickBooks Desktop name ends with this text." }, { "schema": { "type": "string", "minLength": 1, "description": "Lower bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameFrom", "in": "query", "description": "Lower bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Upper bound for QuickBooks Desktop name range filtering." }, "required": false, "name": "nameTo", "in": "query", "description": "Upper bound for QuickBooks Desktop name range filtering." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs by exact total balance." }, "required": false, "name": "totalBalance", "in": "query", "description": "Filters customers or jobs by exact total balance." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance greater than this amount." }, "required": false, "name": "totalBalanceGreaterThan", "in": "query", "description": "Filters customers or jobs with total balance greater than this amount." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance greater than or equal to this amount." }, "required": false, "name": "totalBalanceGreaterThanOrEqualTo", "in": "query", "description": "Filters customers or jobs with total balance greater than or equal to this amount." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance less than this amount." }, "required": false, "name": "totalBalanceLessThan", "in": "query", "description": "Filters customers or jobs with total balance less than this amount." }, { "schema": { "type": "string", "minLength": 1, "description": "Filters customers or jobs with total balance less than or equal to this amount." }, "required": false, "name": "totalBalanceLessThanOrEqualTo", "in": "query", "description": "Filters customers or jobs with total balance less than or equal to this amount." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop currency IDs." }, "required": false, "name": "currencyIds", "in": "query", "description": "Filters records by QuickBooks Desktop currency IDs." }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filters records by QuickBooks Desktop class IDs." }, "required": false, "name": "classIds", "in": "query", "description": "Filters records by QuickBooks Desktop class IDs." }, { "schema": { "type": "boolean", "default": false, "description": "When true, omits alternate shipping addresses from customer responses to reduce QuickBooks Desktop read time." }, "required": false, "name": "excludeAlternateShippingAddresses", "in": "query", "description": "When true, omits alternate shipping addresses from customer responses to reduce QuickBooks Desktop read time." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QbdCustomerListResponseDto" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } } } ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists live QuickBooks Desktop customers and jobs for one connection. This connection-scoped route returns typed customer/job projections with cursor pagination and filtering.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/vendors": { "get": { "summary": "Query live vendors", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/QbdContactResourceDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } }, "required": [ "vendors", "nextKey", "remainingCount" ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Query live vendors.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/accounts": { "get": { "summary": "Query live accounts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/QbdAccountingCodeResourceDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } }, "required": [ "accounts", "nextKey", "remainingCount" ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Query live accounts.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/items": { "get": { "summary": "Query live items", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QbdAccountingCodeResourceDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } }, "required": [ "items", "nextKey", "remainingCount" ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Query live items.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/connections/{id}/invoices": { "get": { "summary": "Query live invoices", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/QbdDocumentResourceDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } }, "required": [ "invoices", "nextKey", "remainingCount" ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Query live invoices.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create invoice in QuickBooks Desktop", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "string", "enum": [ "wait", "immediate" ], "default": "wait", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." }, "required": false, "name": "completionMode", "in": "query", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQbdInvoiceWriteRequestDto" } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks write is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates an invoice in QuickBooks Desktop through one connection. Use it when a trusted internal service already knows the connection ID and wants the connection-scoped write route.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- Write completion depends on the `completionMode` query parameter and current QuickBooks Desktop availability.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/connections/{id}/bills": { "get": { "summary": "Query live bills", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Maximum number of records to return." }, "required": false, "name": "limit", "in": "query", "description": "Maximum number of records to return." }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor returned by the previous connection-scoped list response." }, "required": false, "name": "nextKey", "in": "query", "description": "Opaque cursor returned by the previous connection-scoped list response." }, { "schema": { "type": "string", "enum": [ "live", "mirror", "mirror_then_refresh", "snapshot", "stale_while_revalidate" ], "default": "live", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, "required": false, "name": "readMode", "in": "query", "description": "live uses a QuickBooks round trip (default); mirror reads the opted-in Firestore mirror; mirror_then_refresh serves it and coalesces a due refresh. Legacy snapshot/stale_while_revalidate use the existing DO catalog. Mirror reads initially support native IDs, active status and bounded cursor pagination; other filters fail explicitly. Use search endpoints for prefix lookup." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." }, "required": false, "name": "afterOperationId", "in": "query", "description": "Mirror modes only: require a successful operation from the same connection and generation to be committed to Firestore before returning data; otherwise returns 202 pending or a typed failure." } ], "responses": { "200": { "description": "QuickBooks Desktop data returned successfully.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "bills": { "type": "array", "items": { "$ref": "#/components/schemas/QbdDocumentResourceDto" } }, "nextKey": { "type": "string", "nullable": true }, "remainingCount": { "type": "integer", "nullable": true, "minimum": 0 }, "meta": { "$ref": "#/components/schemas/QbdMirrorReadMetadata" } }, "required": [ "bills", "nextKey", "remainingCount" ] } } } }, "202": { "description": "The selected snapshot, initial mirror scan, or causal write projection is still pending. Mirror requests return a sync identifier in meta and never fall back to a live request.", "headers": { "x-boost-qbd-read-source": { "description": "The execution source used to satisfy the QuickBooks Desktop read.", "schema": { "type": "string", "enum": [ "live_operation", "firestore_mirror", "materialized_snapshot", "coalesced_operation" ] } }, "x-boost-qbd-data-as-of": { "description": "The ISO 8601 timestamp when materialized QuickBooks Desktop data became current.", "schema": { "type": "string", "format": "date-time" } }, "x-boost-qbd-data-stale": { "description": "Whether the returned materialized data is past its adaptive refresh deadline.", "schema": { "type": "boolean" } }, "x-boost-qbd-refresh-id": { "description": "The catalog refresh ID to poll while a materialized snapshot is being built.", "schema": { "type": "string" } }, "x-boost-qbd-operation-id": { "description": "The underlying QuickBooks Desktop operation ID when work was queued or coalesced.", "schema": { "type": "string" } }, "x-boost-qbd-operation-disposition": { "description": "Whether the read created, replayed, or coalesced with an active QuickBooks operation.", "schema": { "type": "string", "enum": [ "created", "idempotent_replay", "active_coalesced" ] } }, "x-boost-qbd-operation-created-at": { "description": "The ISO 8601 timestamp when the underlying QuickBooks Desktop operation was created.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds the client should wait before polling the catalog refresh.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdCatalogRefreshAcceptedDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "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 snapshot/mirror is disabled, its generation changed, its cursor expired, or the requested operation/projection failed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QbdSnapshotErrorDto" }, { "$ref": "#/components/schemas/QbdMirrorReadError" } ] } } } }, "422": { "description": "QuickBooks rejected the read request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Mirror storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdMirrorReadError" } } } }, "504": { "description": "QuickBooks read did not finish before the API timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Query live bills.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.", "x-required-permissions": [ "qbd:read" ] }, "post": { "summary": "Create bill in QuickBooks Desktop", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Boost Connect QBD connection ID." }, "required": true, "name": "id", "in": "path", "description": "The Boost Connect QBD connection ID." }, { "schema": { "type": "string", "enum": [ "wait", "immediate" ], "default": "wait", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." }, "required": false, "name": "completionMode", "in": "query", "description": "Controls whether the API waits for QuickBooks Desktop to finish the write or returns while processing continues." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQbdBillWriteRequestDto" } } }, "description": "JSON fields that Boost Connect translates into the QuickBooks Desktop qbXML request for this write operation." }, "responses": { "200": { "description": "QuickBooks accepted the bill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "202": { "description": "QuickBooks write is still processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "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" } } } }, "422": { "description": "QuickBooks rejected the bill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QbdWriteResultDto" } } } }, "429": { "description": "The account API rate limit was exceeded or the QuickBooks operation queue is full. Retry after the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a bill in QuickBooks Desktop through one connection. Use it when a trusted internal service already knows the connection ID and wants the connection-scoped write route.\n\n**Requirements:**\n- Requires bearer authentication for the owning account or project.\n- Requires a Boost Connect QBD connection ID in the path.\n- Write completion depends on the `completionMode` query parameter and current QuickBooks Desktop availability.", "x-required-permissions": [ "qbd:write" ] } }, "/api/qbd/v1/products": { "get": { "summary": "List mirrored products", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "readMode", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "mirror", "mirror_then_refresh" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "afterOperationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 12000 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "name" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "service", "inventory", "non_inventory", "inventory_assembly", "other_charge", "group" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "parentId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "The connector connection ID authorized for the supplied API credential." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceMirrorList" } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "400": { "description": "Unsupported/invalid filter, combination or cursor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "401": { "description": "Invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "403": { "description": "Missing read permission or project access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "404": { "description": "Connection or ready resource record not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "409": { "description": "Mirror disabled, generation/cursor invalidated or projection failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "429": { "description": "Account-level API throttle exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "503": { "description": "Mirror storage unavailable; no live fallback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } } }, "description": "**Requirements:**\n- Requires a valid connector API credential with qbd:read access to the selected connection's account and project.\n- Requires x-boost-qbd-connection-id and an enabled, initially synchronized mirror.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "type", "parentId", "active" ], "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/products/{id}": { "get": { "summary": "Get mirrored products", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "readMode", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "mirror", "mirror_then_refresh" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "afterOperationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "The connector connection ID authorized for the supplied API credential." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Native record ID, or owner-scoped opaque contact ID, within the selected connection." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceMirrorDetail" } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "400": { "description": "Unsupported/invalid filter, combination or cursor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "401": { "description": "Invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "403": { "description": "Missing read permission or project access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "404": { "description": "Connection or ready resource record not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "409": { "description": "Mirror disabled, generation/cursor invalidated or projection failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "429": { "description": "Account-level API throttle exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "503": { "description": "Mirror storage unavailable; no live fallback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } } }, "description": "**Requirements:**\n- Requires a valid connector API credential with qbd:read access to the selected connection's account and project.\n- Requires x-boost-qbd-connection-id and an enabled, initially synchronized mirror.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-mirror-query-parameters": [ "readMode", "afterOperationId" ], "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/contacts": { "get": { "summary": "List mirrored contacts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "readMode", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "mirror", "mirror_then_refresh" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "afterOperationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 12000 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "name" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "updatedBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "ownerType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "customer", "job", "vendor" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "The connector connection ID authorized for the supplied API credential." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceMirrorList" } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "400": { "description": "Unsupported/invalid filter, combination or cursor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "401": { "description": "Invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "403": { "description": "Missing read permission or project access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "404": { "description": "Connection or ready resource record not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "409": { "description": "Mirror disabled, generation/cursor invalidated or projection failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "429": { "description": "Account-level API throttle exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "503": { "description": "Mirror storage unavailable; no live fallback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } } }, "description": "**Requirements:**\n- Requires a valid connector API credential with qbd:read access to the selected connection's account and project.\n- Requires x-boost-qbd-connection-id and an enabled, initially synchronized mirror.\n\nMirror mode uses the ResourceMirrorList response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-mirror-query-parameters": [ "readMode", "afterOperationId", "limit", "cursor", "sort", "order", "createdFrom", "createdBefore", "updatedFrom", "updatedBefore", "q", "ownerType", "ownerId", "email" ], "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/contacts/{id}": { "get": { "summary": "Get mirrored contacts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "readMode", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "mirror", "mirror_then_refresh" ] }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "afterOperationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Supported for readMode=mirror or mirror_then_refresh." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "The connector connection ID authorized for the supplied API credential." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Native record ID, or owner-scoped opaque contact ID, within the selected connection." } ], "responses": { "200": { "description": "Mirror response uses the explicit resource envelope; other read modes retain their native response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceMirrorDetail" } } } }, "202": { "description": "Mirror mode: initial build or projection pending, with resource-family metadata and no data. Other modes retain their native pending response.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } }, { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "$ref": "#/components/schemas/ResourceMirrorMetadata" } } } ] } } } }, "400": { "description": "Unsupported/invalid filter, combination or cursor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "401": { "description": "Invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "403": { "description": "Missing read permission or project access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "404": { "description": "Connection or ready resource record not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "409": { "description": "Mirror disabled, generation/cursor invalidated or projection failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "429": { "description": "Account-level API throttle exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } }, "503": { "description": "Mirror storage unavailable; no live fallback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "minLength": 1, "maxLength": 512 }, "meta": { "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" } } } } } } } } } }, "description": "**Requirements:**\n- Requires a valid connector API credential with qbd:read access to the selected connection's account and project.\n- Requires x-boost-qbd-connection-id and an enabled, initially synchronized mirror.\n\nMirror mode uses the ResourceMirrorDetail response. Only x-mirror-query-parameters are accepted in this mode. All filters are ANDed. IDs are connection-scoped; customerId matches exactly, without descendant rollup. Email/refNumber return non-unique lists. Email is case-normalized; refNumber is exact and preserves zeros. q is literal token-prefix search. From is inclusive and Before exclusive. ownerId requires ownerType. Mirror limit defaults/maxes at 100; document lines default off on lists and on in details. Cursors bind scope, generation, filters and sort; paging is not a frozen snapshot. No silent live fallback. Data can be read while QBWC is offline after bootstrap. afterOperationId requires committed projection; pending returns 202. Native people have owner-scoped IDs, not shared CRM identities. See docs/architecture/resource-mirror-api-contract.md.", "x-mirror-query-parameters": [ "readMode", "afterOperationId" ], "x-required-permissions": [ "qbd:read" ] } }, "/api/qbd/v1/customers/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked customers write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/customers/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked customers write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/vendors/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked vendors write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/vendors/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked vendors write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/invoices/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked invoices write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/invoices/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked invoices write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/sales-orders/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked sales-orders write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/sales-orders/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked sales-orders write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/estimates/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked estimates write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/estimates/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked estimates write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/service-items/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked service-items write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/service-items/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked service-items write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/inventory-items/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked inventory-items write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/inventory-items/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked inventory-items write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/non-inventory-items/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked non-inventory-items write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/non-inventory-items/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked non-inventory-items write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/inventory-assembly-items/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked inventory-assembly-items write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/inventory-assembly-items/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked inventory-assembly-items write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/other-charge-items/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked other-charge-items write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/other-charge-items/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked other-charge-items write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/item-groups/{id}/writes/{writeId}/cancel": { "post": { "summary": "Cancel an undispatched tracked item-groups write", "description": "Human recovery. Cancellation is atomic against QBWC claiming the queued operation. Claimed/unknown writes and writes with later queued edits return 409. Cancelled creates remain visible as failed; cancelled updates restore confirmed values. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "responses": { "200": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } }, "/api/qbd/v1/item-groups/{id}/writes/{writeId}/retry": { "post": { "summary": "Retry a known failed tracked item-groups write", "description": "Human recovery. Only an explicit rejection, cancellation, or an expired command proven never submitted may be retried. Unknown outcomes cannot be retried. Reuses the business record identity with a new command identity and deadline. Optional replacementBody replaces the submitted fields for this attempt, allowing a human to correct an error or supply an explicitly refreshed revision. For contact writes use the owning customers/{id} and the contact's writeId.\n\n**Requirements:** API key with qbd:write permission for the connection's project, an enabled mirror, and Idempotency-Key.", "security": [ { "BearerAuth": [] } ], "x-required-permissions": [ "qbd:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable record ID (the owner customer/job for a contact write)." }, { "name": "writeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command writeId from the receipt or record sync metadata." }, { "name": "x-boost-qbd-connection-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target QuickBooks Desktop connection authorized by the API key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "description": "Required in tracked mode. Reuse for exactly the same request after a transport failure." } ], "requestBody": { "description": "Optional corrected native write fields; omitted means retry the same fields. Include the full intended create payload for a create retry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "replacementBody" ], "properties": { "replacementBody": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingWriteReceipt" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credential" }, "403": { "description": "Unauthorized connection/project" }, "404": { "description": "Record/write not found" }, "409": { "description": "Unsafe recovery or replay conflict; no replacement command submitted" }, "503": { "description": "Temporarily unavailable; retry the same key" } } } } } }