--- title: "Update organization" description: "Updates exactly one organization settings section. The section selects the request shape. For a logo, prepare an organization_logo upload, send the image bytes to uploadUrl, then submit its fileRef in the branding section." language: en canonical_url: "https://exac.mx/docs/en/api/workspace/organization/update-organization" md_url: "https://exac.mx/docs/en/api/workspace/organization/update-organization.md" --- # Update organization Updates exactly one organization settings section. The section selects the request shape. For a logo, prepare an organization_logo upload, send the image bytes to uploadUrl, then submit its fileRef in the branding section. ## Request `PATCH /v1/organization` - **Authorization:** Permission depends on the body `section`: `profile` → `org:update`, `fiscal` → `settings:update`, `branding` → `settings:update`, `portal` → `settings:update`, `globalInvoice` → `settings:update`, `automation` → `settings:update`, `access` → `org:update`. - **Environments:** Production only - **Idempotency:** Required ## Canonical machine contract This fragment is generated from the canonical operation and Zod contracts used by the route. ```json { "method": "PATCH", "path": "/v1/organization", "operation": { "operationId": "updateOrganization", "tags": [ "Organization" ], "summary": "Update organization", "description": "Updates exactly one organization settings section. The section selects the request shape. For a logo, prepare an organization_logo upload, send the image bytes to uploadUrl, then submit its fileRef in the branding section.", "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://adventurous-moose-616.convex.site", "description": "Current Exac production API deployment" } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "section": { "type": "string", "const": "profile" }, "name": { "type": "string", "minLength": 1 }, "timeZone": { "type": "string", "minLength": 1 } }, "required": [ "section" ], "additionalProperties": false }, { "type": "object", "properties": { "section": { "type": "string", "const": "fiscal" }, "legalName": { "type": "string", "minLength": 1, "maxLength": 100 }, "rfc": { "type": "string", "minLength": 12, "maxLength": 13 }, "taxSystem": { "description": "Active SAT tax-system code.", "x-exac-sat-catalog": "tax-systems", "oneOf": [ { "type": "string", "title": "SAT c_RegimenFiscal", "description": "View active codes and official names [here](/docs/en/sat-catalogs/invoicing#tax-systems).", "enum": [ "601", "603", "605", "606", "607", "608", "610", "611", "612", "614", "615", "616", "620", "621", "622", "623", "624", "625", "626" ] } ] }, "address": { "type": "object", "properties": { "postalCode": { "type": "string", "pattern": "^\\d{5}$" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "exterior": { "type": "string" }, "interior": { "type": "string" }, "neighborhood": { "type": "string" }, "municipality": { "type": "string" } }, "required": [ "postalCode" ], "additionalProperties": false }, "usesBorderRegionStimulus": { "type": "boolean" }, "website": { "type": "string", "format": "uri" }, "phone": { "type": "string" } }, "required": [ "section", "legalName", "taxSystem", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "section": { "type": "string", "const": "branding" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "pdfOptions": { "type": "object", "properties": { "codes": { "type": "boolean" }, "productKey": { "type": "boolean" }, "roundUnitPrice": { "type": "boolean" }, "taxBreakdown": { "type": "boolean" }, "iepsBreakdown": { "type": "boolean" }, "renderCartaPorte": { "type": "boolean" } }, "required": [ "codes", "productKey", "roundUnitPrice", "taxBreakdown", "iepsBreakdown", "renderCartaPorte" ], "additionalProperties": false }, "logo": { "type": "object", "properties": { "fileRef": { "type": "string", "minLength": 1 } }, "required": [ "fileRef" ], "additionalProperties": false } }, "required": [ "section" ], "additionalProperties": false }, { "type": "object", "properties": { "section": { "type": "string", "const": "portal" }, "slug": { "type": "string", "minLength": 3, "maxLength": 30 }, "enabled": { "type": "boolean" }, "welcomeText": { "type": "string" }, "supportEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "allowedCfdiUses": { "type": "array", "items": { "description": "Active SAT CFDI-use code.", "x-exac-sat-catalog": "cfdi-uses", "oneOf": [ { "type": "string", "title": "SAT c_UsoCFDI", "description": "View active codes and official names [here](/docs/en/sat-catalogs/invoicing#cfdi-uses).", "enum": [ "G01", "D06", "I07", "I06", "I01", "I05", "D09", "G02", "D04", "I04", "I03", "D08", "G03", "D03", "D02", "D01", "D05", "I02", "CN01", "I08", "CP01", "D10", "D07", "S01" ] } ] } }, "receiptExpirationDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 365 }, { "type": "null" } ] }, "receiptStartingFolio": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "receiptNextFolio": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "receiptLocationScopedFolios": { "type": "boolean" }, "receiptPrintWidth": { "type": "string", "enum": [ "45mm", "58mm", "80mm", "112mm", "letter" ] }, "receiptLocationRequired": { "type": "boolean" }, "receiptShowQrCode": { "type": "boolean" }, "inventoryBlockOnNegativeStock": { "type": "boolean" } }, "required": [ "section" ], "additionalProperties": false }, { "type": "object", "properties": { "section": { "type": "string", "const": "globalInvoice" }, "enabled": { "type": "boolean" }, "periodicity": { "type": "string", "enum": [ "day", "week", "fortnight", "month", "two_months" ] }, "eligibilityStartAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "section" ], "additionalProperties": false }, { "type": "object", "properties": { "section": { "type": "string", "const": "automation" }, "cfdiSyncEnabled": { "type": "boolean" }, "declarationSyncEnabled": { "type": "boolean" } }, "required": [ "section" ], "additionalProperties": false }, { "type": "object", "properties": { "section": { "type": "string", "const": "access" }, "pricingDisplay": { "type": "string", "enum": [ "show", "hide" ] }, "canCancelReceipts": { "type": "boolean" } }, "required": [ "section", "pricingDisplay", "canCancelReceipts" ], "additionalProperties": false } ] }, "example": { "section": "branding", "logo": { "fileRef": "file:example" } } } } }, "responses": { "200": { "description": "Operation completed.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "timeZone": { "type": "string" }, "branding": { "type": "object", "properties": { "color": { "type": "string" }, "logoUrl": { "type": "string" }, "pdfOptions": { "type": "object", "properties": { "codes": { "type": "boolean" }, "productKey": { "type": "boolean" }, "roundUnitPrice": { "type": "boolean" }, "taxBreakdown": { "type": "boolean" }, "iepsBreakdown": { "type": "boolean" }, "renderCartaPorte": { "type": "boolean" } }, "required": [ "codes", "productKey", "roundUnitPrice", "taxBreakdown", "iepsBreakdown", "renderCartaPorte" ], "additionalProperties": false } }, "additionalProperties": false }, "readiness": { "type": "object", "properties": { "production": { "type": "boolean" }, "csd": { "type": "boolean" }, "fiel": { "type": "boolean" } }, "required": [ "production", "csd", "fiel" ], "additionalProperties": false }, "certificates": { "type": "object", "properties": { "csd": { "type": "object", "properties": { "configured": { "type": "boolean" }, "expiresAt": { "type": "string" }, "serialNumber": { "type": "string" } }, "required": [ "configured" ], "additionalProperties": false }, "fiel": { "type": "object", "properties": { "configured": { "type": "boolean" }, "expiresAt": { "type": "string" } }, "required": [ "configured" ], "additionalProperties": false } }, "required": [ "csd", "fiel" ], "additionalProperties": false }, "portal": { "type": "object", "properties": { "slug": { "type": "string" }, "enabled": { "type": "boolean" }, "welcomeText": { "type": "string" }, "supportEmail": { "type": "string" }, "allowedCfdiUses": { "type": "array", "items": { "type": "string" } }, "receiptExpirationDays": { "type": "number" }, "receiptStartingFolio": { "type": "number" }, "receiptNextFolio": { "type": "number" }, "receiptLocationScopedFolios": { "type": "boolean" }, "receiptPrintWidth": { "type": "string" }, "receiptLocationRequired": { "type": "boolean" }, "receiptShowQrCode": { "type": "boolean" }, "inventoryBlockOnNegativeStock": { "type": "boolean" } }, "required": [ "enabled", "receiptLocationScopedFolios", "receiptLocationRequired", "receiptShowQrCode", "inventoryBlockOnNegativeStock" ], "additionalProperties": false }, "automation": { "type": "object", "properties": { "cfdiSyncEnabled": { "type": "boolean" }, "declarationSyncEnabled": { "type": "boolean" } }, "required": [ "cfdiSyncEnabled", "declarationSyncEnabled" ], "additionalProperties": false }, "cashierAccess": { "type": "object", "properties": { "pricingDisplay": { "type": "string", "enum": [ "show", "hide" ] }, "canCancelReceipts": { "type": "boolean" } }, "required": [ "pricingDisplay", "canCancelReceipts" ], "additionalProperties": false }, "fiscal": { "type": "object", "properties": { "legalName": { "type": "string" }, "rfc": { "type": "string" }, "taxSystem": { "type": "string" }, "rfcPersonType": { "type": "string" }, "usesBorderRegionStimulus": { "type": "boolean" }, "website": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "exterior": { "type": "string" }, "interior": { "type": "string" }, "neighborhood": { "type": "string" }, "municipality": { "type": "string" }, "postalCode": { "type": "string" } }, "required": [ "postalCode" ], "additionalProperties": false } }, "additionalProperties": false }, "globalInvoice": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "periodicity": { "type": "string" }, "eligibilityStartAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "lastRunAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "enabled" ], "additionalProperties": false } }, "required": [ "name", "timeZone", "branding", "readiness", "certificates", "portal", "automation", "fiscal", "globalInvoice" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "name": "Ejemplo SA de CV", "timeZone": "America/Mexico_City", "branding": {}, "readiness": { "production": false, "csd": false, "fiel": false }, "certificates": { "csd": { "configured": false }, "fiel": { "configured": false } }, "portal": { "enabled": false, "receiptLocationScopedFolios": true, "receiptLocationRequired": false, "receiptShowQrCode": true, "inventoryBlockOnNegativeStock": false }, "automation": { "cfdiSyncEnabled": false, "declarationSyncEnabled": false }, "fiscal": {}, "globalInvoice": { "enabled": false } } } } } }, "400": { "description": "Invalid request.\n\n`validation_error`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid credential.\n\n`unauthenticated`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The credential does not satisfy the required authorization. Permission depends on the body `section`: `profile` → `org:update`, `fiscal` → `settings:update`, `branding` → `settings:update`, `portal` → `settings:update`, `globalInvoice` → `settings:update`, `automation` → `settings:update`, `access` → `org:update`.\n\n`forbidden`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found.\n\n`not_found`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Method not allowed.\n\n`method_not_allowed`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The operation conflicts with its current state or idempotency key.\n\nPossible codes: `conflict`, `idempotency_conflict`, `operation_in_progress`, `recovery_required`.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests.\n\n`rate_limited`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error.\n\n`internal`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service temporarily unavailable.\n\n`provider_unavailable`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-exac-environments": [ "production" ] }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ProgrammaticError" } }, "required": [ "error" ], "additionalProperties": false }, "ProgrammaticError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "unauthenticated", "forbidden", "not_found", "method_not_allowed", "conflict", "idempotency_conflict", "operation_in_progress", "recovery_required", "rate_limited", "provider_unavailable", "internal" ], "description": "Recommended action by code:\n\n- `validation_error` — Correct each details.issues entry using its path and stable issue code.\n- `unauthenticated` — Provide a valid API key or OAuth access token.\n- `forbidden` — Use a credential with the required permission.\n- `not_found` — Check the organization-scoped resource identifier.\n- `method_not_allowed` — Use the documented HTTP method.\n- `conflict` — Refresh the resource and resolve its current state.\n- `idempotency_conflict` — Use a new idempotency key for a changed request.\n- `operation_in_progress` — Wait for Retry-After, then repeat the exact request.\n- `recovery_required` — Do not retry automatically; reconcile the provider outcome.\n- `rate_limited` — Wait for Retry-After before retrying.\n- `provider_unavailable` — Retry only when the response marks the failure as retryable.\n- `internal` — Retry later and contact support if the error persists." }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "message", "status" ], "additionalProperties": false } } } } ``` [OpenAPI 3.1](/openapi.json) ## Equivalent MCP tools - [`update_organization`](/docs/en/mcp/tools/update_organization.md) Complete documentation: https://exac.mx/docs/en.md Agent documentation index: https://exac.mx/docs/en/llms.txt