business.update

Update the business description, website, logo or postal address, or submit a YC verification link. Legal identity and the business slug are separate from these profile fields.

What it does

Update the ordinary business profile (description, website, the logo its share pages show, postal address for invoices and applicable DPA annexes), or submit a YC verification link for server-side checking. The legal name, legal form and jurisdiction are not profile fields: change them with business.change_legal_name and business.change_legal_form. The business slug is its immutable routing address and cannot be changed through this public command.

Before you send it

An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe business.update through GET /v1/catalog/commands/{name} before acting.

This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.

Inputs

Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.

Required means required within its containing object; an optional parent can be omitted.

After acceptance

When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.

Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.

Result fields

Required means required within its containing object; an optional parent can be omitted.

All commands · Operation and errors · Reusable schemas

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

Exact request schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "const": "business.update"
    },
    "input": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$",
          "description": "The public name the workspace and shared pages show. The legal name changes with business.change_legal_name."
        },
        "description": {
          "type": "string",
          "maxLength": 280,
          "pattern": "^[^\\r\\n]*$"
        },
        "address": {
          "type": "object",
          "properties": {
            "line1": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]+$"
            },
            "line2": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]*$"
            },
            "city": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]+$"
            },
            "region": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]*$"
            },
            "postalCode": {
              "type": "string",
              "maxLength": 40,
              "pattern": "^[^\\r\\n]*$"
            },
            "country": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            }
          },
          "required": [
            "line1",
            "city",
            "country"
          ],
          "additionalProperties": false
        },
        "url": {
          "type": "string",
          "pattern": "^https?://[^\\s/]+",
          "maxLength": 2048
        },
        "logoUrl": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "description": "A logo in Economico's shared public images, as the canonical https://logos.economi.co/logos/{owner-id}/{cid}.{png|jpg|webp} link an upload returns. The form is checked, not looked up: any link in that form is accepted, and any other link is refused. Anyone with the link can view the image; after replacing an image, set its new link here. Shown on the business's share pages. Omit it to keep the current logo; null clears it."
        },
        "ycVerificationUrl": {
          "type": "string",
          "pattern": "^https://(?:www\\.)?ycombinator\\.com/verify/[A-Za-z0-9]+/?$"
        }
      },
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500,
              "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$",
              "description": "The public name the workspace and shared pages show. The legal name changes with business.change_legal_name."
            }
          },
          "required": [
            "name"
          ]
        },
        {
          "type": "object",
          "properties": {
            "description": {
              "type": "string",
              "maxLength": 280,
              "pattern": "^[^\\r\\n]*$"
            }
          },
          "required": [
            "description"
          ]
        },
        {
          "type": "object",
          "properties": {
            "address": {
              "type": "object",
              "properties": {
                "line1": {
                  "type": "string",
                  "maxLength": 200,
                  "pattern": "^[^\\r\\n]+$"
                },
                "line2": {
                  "type": "string",
                  "maxLength": 200,
                  "pattern": "^[^\\r\\n]*$"
                },
                "city": {
                  "type": "string",
                  "maxLength": 200,
                  "pattern": "^[^\\r\\n]+$"
                },
                "region": {
                  "type": "string",
                  "maxLength": 200,
                  "pattern": "^[^\\r\\n]*$"
                },
                "postalCode": {
                  "type": "string",
                  "maxLength": 40,
                  "pattern": "^[^\\r\\n]*$"
                },
                "country": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$"
                }
              },
              "required": [
                "line1",
                "city",
                "country"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "address"
          ]
        },
        {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "pattern": "^https?://[^\\s/]+",
              "maxLength": 2048
            }
          },
          "required": [
            "url"
          ]
        },
        {
          "type": "object",
          "properties": {
            "logoUrl": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "description": "A logo in Economico's shared public images, as the canonical https://logos.economi.co/logos/{owner-id}/{cid}.{png|jpg|webp} link an upload returns. The form is checked, not looked up: any link in that form is accepted, and any other link is refused. Anyone with the link can view the image; after replacing an image, set its new link here. Shown on the business's share pages. Omit it to keep the current logo; null clears it."
            }
          },
          "required": [
            "logoUrl"
          ]
        },
        {
          "type": "object",
          "properties": {
            "ycVerificationUrl": {
              "type": "string",
              "pattern": "^https://(?:www\\.)?ycombinator\\.com/verify/[A-Za-z0-9]+/?$"
            }
          },
          "required": [
            "ycVerificationUrl"
          ]
        }
      ],
      "additionalProperties": false
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "effective_at": {
      "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))$"
    }
  },
  "required": [
    "name",
    "input",
    "idempotency_key",
    "effective_at"
  ],
  "additionalProperties": false
}

Accepted command receipt

{
  "type": "object",
  "required": [
    "commandId",
    "replayed",
    "result",
    "events"
  ],
  "properties": {
    "commandId": {
      "type": "string"
    },
    "replayed": {
      "type": "boolean"
    },
    "imported": {
      "const": true,
      "description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
    },
    "result": {
      "type": "object",
      "properties": {
        "demo": {
          "const": true,
          "description": "Present only on a demo business: a fictional company, its owner's alone, that never takes a plan or reaches anyone but Economico, which it can send support requests and suggestions. Its figures are not real."
        },
        "demoOpenedAt": {
          "type": "string",
          "format": "date-time",
          "description": "On a demo business: when it was opened. Its seeded books run up to here."
        },
        "name": {
          "type": "string",
          "description": "The public name."
        },
        "legalName": {
          "type": "string",
          "description": "The registered name agreements and documents use; a project's is its owner's."
        },
        "legalEntityType": {
          "enum": [
            "unknown",
            "llc",
            "c_corp",
            "s_corp",
            "sole_proprietorship",
            "partnership",
            "nonprofit",
            "unincorporated",
            "other",
            "private_limited_company",
            "corporation",
            "stock_corporation",
            "project"
          ]
        },
        "ownership": {
          "type": "object",
          "description": "What the legal form means for equity: the balance sheet's equity heading, the ownership reports that apply (primary first) and the company-setup skill's ownership recipes.",
          "properties": {
            "family": {
              "enum": [
                "corporation",
                "members",
                "partners",
                "owner",
                "nonprofit",
                "unspecified"
              ]
            },
            "equityLabel": {
              "type": "string"
            },
            "reports": {
              "type": "array",
              "items": {
                "enum": [
                  "cap_table",
                  "capital_accounts"
                ]
              }
            },
            "recipes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "family",
            "equityLabel",
            "reports",
            "recipes"
          ]
        },
        "jurisdiction": {
          "type": "string"
        },
        "formationDate": {
          "type": "string",
          "format": "date"
        },
        "formationDateEventId": {
          "type": "integer"
        },
        "nameEventId": {
          "type": "integer"
        },
        "legalNameEventId": {
          "type": "integer"
        },
        "legalEntityTypeEventId": {
          "type": "integer"
        },
        "jurisdictionEventId": {
          "type": "integer"
        },
        "registrations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "enum": [
                  "us_ein",
                  "sg_uen",
                  "ca_bn",
                  "gb_company_number"
                ]
              },
              "number": {
                "type": "string"
              },
              "eventId": {
                "type": "integer"
              }
            },
            "required": [
              "kind",
              "number",
              "eventId"
            ]
          }
        },
        "description": {
          "type": "string"
        },
        "address": {
          "type": "object",
          "properties": {
            "line1": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]+$"
            },
            "line2": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]*$"
            },
            "city": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]+$"
            },
            "region": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^[^\\r\\n]*$"
            },
            "postalCode": {
              "type": "string",
              "maxLength": 40,
              "pattern": "^[^\\r\\n]*$"
            },
            "country": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            }
          },
          "required": [
            "line1",
            "city",
            "country"
          ],
          "additionalProperties": false
        },
        "url": {
          "type": "string",
          "pattern": "^https?://"
        },
        "slug": {
          "type": "string"
        },
        "functionalCurrency": {
          "type": "string"
        },
        "primaryLedgerId": {
          "type": "string"
        },
        "successions": {
          "type": "array",
          "description": "Incorporations in place (business.incorporate), oldest first.",
          "items": {
            "type": "object",
            "properties": {
              "eventId": {
                "type": "integer"
              },
              "effectiveAt": {
                "type": "string"
              },
              "previousName": {
                "type": "string"
              },
              "previousLegalEntityType": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "legalEntityType": {
                "type": "string"
              },
              "predecessorLedgerId": {
                "type": "string"
              },
              "successorLedgerId": {
                "type": "string"
              }
            },
            "required": [
              "eventId",
              "effectiveAt",
              "previousLegalEntityType",
              "name",
              "legalEntityType",
              "predecessorLedgerId",
              "successorLedgerId"
            ]
          }
        },
        "functionalCurrencyPeriods": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "currency": {
                "type": "string"
              },
              "ledgerId": {
                "type": "string"
              },
              "effectiveFrom": {
                "type": "string"
              },
              "effectiveUntil": {
                "type": "string"
              },
              "changeEventId": {
                "type": "integer"
              }
            },
            "required": [
              "currency",
              "ledgerId",
              "effectiveFrom",
              "changeEventId"
            ]
          }
        },
        "accountingFramework": {
          "type": "object",
          "required": [
            "framework",
            "reason",
            "jurisdiction",
            "evidenceDocumentId",
            "evidenceDocumentCid",
            "effectiveAt"
          ],
          "properties": {
            "framework": {
              "type": "string"
            },
            "edition": {
              "type": "string"
            },
            "sizeRegime": {
              "enum": [
                "small",
                "micro"
              ]
            },
            "sizeEligibility": {
              "type": "object",
              "required": [
                "basis",
                "periodEnd"
              ],
              "properties": {
                "basis": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 2000,
                  "description": "What the founder's size conclusion rests on, e.g. 'Companies Act 2006 s384A conditions met in FY2025 and FY2026'. Recorded, never computed."
                },
                "periodEnd": {
                  "type": "string",
                  "format": "date",
                  "description": "Period end the conclusion covers."
                }
              }
            },
            "reason": {
              "type": "string"
            },
            "jurisdiction": {
              "type": "string"
            },
            "evidenceDocumentId": {
              "type": "string"
            },
            "evidenceDocumentCid": {
              "type": "string"
            },
            "effectiveAt": {
              "type": "string"
            },
            "eventId": {
              "type": "integer"
            }
          }
        },
        "accountingFrameworkHistory": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "framework",
              "reason",
              "jurisdiction",
              "evidenceDocumentId",
              "evidenceDocumentCid",
              "effectiveAt"
            ],
            "properties": {
              "framework": {
                "type": "string"
              },
              "edition": {
                "type": "string"
              },
              "sizeRegime": {
                "enum": [
                  "small",
                  "micro"
                ]
              },
              "sizeEligibility": {
                "type": "object",
                "required": [
                  "basis",
                  "periodEnd"
                ],
                "properties": {
                  "basis": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000,
                    "description": "What the founder's size conclusion rests on, e.g. 'Companies Act 2006 s384A conditions met in FY2025 and FY2026'. Recorded, never computed."
                  },
                  "periodEnd": {
                    "type": "string",
                    "format": "date",
                    "description": "Period end the conclusion covers."
                  }
                }
              },
              "reason": {
                "type": "string"
              },
              "jurisdiction": {
                "type": "string"
              },
              "evidenceDocumentId": {
                "type": "string"
              },
              "evidenceDocumentCid": {
                "type": "string"
              },
              "effectiveAt": {
                "type": "string"
              },
              "eventId": {
                "type": "integer"
              }
            }
          }
        },
        "salesTaxRegistrations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "registrationId": {
                "type": "string"
              },
              "regime": {
                "enum": [
                  "sg_gst",
                  "ca_gst_hst",
                  "ca_qst",
                  "ca_pst_bc",
                  "ca_pst_sk",
                  "ca_rst_mb",
                  "gb_vat"
                ],
                "description": "sg_gst (Singapore GST); ca_gst_hst (Canadian GST/HST), ca_qst (Quebec QST), ca_pst_bc, ca_pst_sk, ca_rst_mb (provincial sales taxes, kept apart from GST/HST); gb_vat (UK VAT). It must be a regime of the country the business is incorporated in. There is no US regime: record US state sales tax as custom codes with tax_codes.create."
              },
              "country": {
                "type": "string"
              },
              "registrationNumber": {
                "type": "string"
              },
              "province": {
                "type": "string"
              },
              "effectiveFrom": {
                "type": "string",
                "format": "date"
              },
              "effectiveUntil": {
                "type": "string",
                "format": "date"
              },
              "reason": {
                "type": "string"
              },
              "sourceDocumentId": {
                "type": "string"
              }
            },
            "required": [
              "registrationId",
              "regime",
              "country",
              "registrationNumber",
              "effectiveFrom",
              "reason",
              "sourceDocumentId"
            ]
          }
        },
        "logoUrl": {
          "type": "string",
          "format": "uri",
          "description": "The logo the business's share pages show."
        },
        "logoCid": {
          "type": "string",
          "description": "The CID in logoUrl."
        },
        "ycVerified": {
          "type": "boolean"
        },
        "ycVerificationUrl": {
          "type": "string"
        },
        "ycVerifiedAt": {
          "type": "string"
        },
        "ycBatch": {
          "type": "string"
        },
        "ycFounderName": {
          "type": "string"
        },
        "ycVerificationPending": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string"
            },
            "requestedAt": {
              "type": "string"
            }
          },
          "required": [
            "url",
            "requestedAt"
          ]
        },
        "ycVerificationError": {
          "type": "string"
        }
      },
      "required": [
        "ycVerified"
      ]
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}

Example request

{
  "name": "business.update",
  "input": {
    "description": "Accounting for agent-run startups",
    "url": "https://example.com"
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "business.update-example-0"
}

Example request

{
  "name": "business.update",
  "input": {
    "ycVerificationUrl": "https://www.ycombinator.com/verify/Example123"
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "business.update-example-1"
}