> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Upsert Catalog Object

> Creates a new or updates the specified [CatalogObject](entity:CatalogObject).

`square.upsertCatalogObject` creates a new or updates the specified [CatalogObject](entity:CatalogObject).

## Example

```ts automations/square-upsert-catalog-object.automation.ts theme={null}
import { automation, onDashboardRun } from "automate.ax"
import { square } from "automate.ax/square"

export default automation("Upsert Square Catalog Object", () => {
  onDashboardRun({ title: "Upsert Square Catalog Object" })

  square.upsertCatalogObject({
    idempotencyKey: "af3d1afc-7212-4300-b463-0bfc5314a5ae",
    object: {
      type: "ITEM",
      id: "id",
    },
  })
})
```

## Inputs

Every input accepts a compatible signal. It requires `ITEMS_WRITE`.

| Field            | Type                   | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ---------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idempotencyKey` | `string`               | Yes      | —       | A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information. |
| `object`         | `Square.CatalogObject` | Yes      | —       | A CatalogObject to be created or updated. - For updates, the object must be active (the `is_deleted` field is not `true`). - For creates, the object ID must start with `#`. The provided ID is replaced with a server-generated ID.                                                                                                                                                                                                                                              |

Use the official [UpsertCatalogObject reference](https://developer.squareup.com/reference/square/catalog-api/upsert-catalog-object) for provider field semantics and limits.

## Output

Returns the official `Square.UpsertCatalogObjectResponse` response as a codec-safe object. Square integer money amounts remain `bigint` values.