# watermarks.replace

> Replace an existing watermark while retaining its stable identity and owner scope. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.



- Member path: `doc.watermarks.replace(…)`
- Mutates document: yes
- Idempotency: `conditional`
- Supports tracked mode: no
- Supports dry run: yes

## Expected result

Returns the replaced watermark, or TARGET_NOT_FOUND when its identity is stale.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "target": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "watermark"
        },
        "watermarkId": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "watermarkId"
      ]
    },
    "watermark": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "text"
            },
            "text": {
              "type": "string",
              "minLength": 1
            },
            "fontFamily": {
              "type": "string",
              "minLength": 1
            },
            "fontSizePt": {
              "oneOf": [
                {
                  "const": "auto"
                },
                {
                  "type": "number",
                  "exclusiveMinimum": 0
                }
              ]
            },
            "bold": {
              "type": "boolean"
            },
            "italic": {
              "type": "boolean"
            },
            "color": {
              "type": "string",
              "pattern": "^#[0-9A-Fa-f]{6}$"
            },
            "opacity": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "orientation": {
              "enum": [
                "horizontal",
                "diagonal"
              ]
            },
            "placement": {
              "type": "object",
              "properties": {
                "widthPt": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "heightPt": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "rotationDegrees": {
                  "type": "number"
                },
                "behindText": {
                  "type": "boolean"
                },
                "horizontal": {
                  "type": "object",
                  "properties": {
                    "relativeFrom": {
                      "enum": [
                        "page",
                        "margin"
                      ]
                    },
                    "alignment": {
                      "enum": [
                        "left",
                        "center",
                        "right"
                      ]
                    },
                    "offsetPt": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "relativeFrom"
                  ]
                },
                "vertical": {
                  "type": "object",
                  "properties": {
                    "relativeFrom": {
                      "enum": [
                        "page",
                        "margin"
                      ]
                    },
                    "alignment": {
                      "enum": [
                        "top",
                        "center",
                        "bottom"
                      ]
                    },
                    "offsetPt": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "relativeFrom"
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "text"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "picture"
            },
            "src": {
              "type": "string",
              "minLength": 1
            },
            "scalePercent": {
              "enum": [
                "auto",
                50,
                100,
                150,
                200,
                500
              ]
            },
            "widthPt": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "heightPt": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "lockAspectRatio": {
              "type": "boolean"
            },
            "washout": {
              "type": "boolean"
            },
            "opacity": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "placement": {
              "type": "object",
              "properties": {
                "widthPt": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "heightPt": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "rotationDegrees": {
                  "type": "number"
                },
                "behindText": {
                  "type": "boolean"
                },
                "horizontal": {
                  "type": "object",
                  "properties": {
                    "relativeFrom": {
                      "enum": [
                        "page",
                        "margin"
                      ]
                    },
                    "alignment": {
                      "enum": [
                        "left",
                        "center",
                        "right"
                      ]
                    },
                    "offsetPt": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "relativeFrom"
                  ]
                },
                "vertical": {
                  "type": "object",
                  "properties": {
                    "relativeFrom": {
                      "enum": [
                        "page",
                        "margin"
                      ]
                    },
                    "alignment": {
                      "enum": [
                        "top",
                        "center",
                        "bottom"
                      ]
                    },
                    "offsetPt": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "relativeFrom"
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "kind",
            "src"
          ]
        }
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "target",
    "watermark"
  ]
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "SectionAddress": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "section"
        },
        "sectionId": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "sectionId"
      ]
    }
  },
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "success": {
          "const": true
        },
        "watermark": {
          "type": "object",
          "properties": {
            "watermarkId": {
              "type": "string"
            },
            "owner": {
              "type": "object",
              "properties": {
                "refId": {
                  "type": "string"
                },
                "partPath": {
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "refId",
                "partPath"
              ]
            },
            "effectiveIn": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "const": "headerFooterSlot"
                  },
                  "section": {
                    "$ref": "#/$defs/SectionAddress"
                  },
                  "headerFooterKind": {
                    "const": "header"
                  },
                  "variant": {
                    "enum": [
                      "default",
                      "first",
                      "even"
                    ]
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "section",
                  "headerFooterKind",
                  "variant"
                ]
              }
            },
            "watermark": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "const": "text"
                    },
                    "text": {
                      "type": "string",
                      "minLength": 1
                    },
                    "fontFamily": {
                      "type": "string",
                      "minLength": 1
                    },
                    "fontSizePt": {
                      "oneOf": [
                        {
                          "const": "auto"
                        },
                        {
                          "type": "number",
                          "exclusiveMinimum": 0
                        }
                      ]
                    },
                    "bold": {
                      "type": "boolean"
                    },
                    "italic": {
                      "type": "boolean"
                    },
                    "color": {
                      "type": "string",
                      "pattern": "^#[0-9A-Fa-f]{6}$"
                    },
                    "opacity": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "orientation": {
                      "enum": [
                        "horizontal",
                        "diagonal"
                      ]
                    },
                    "placement": {
                      "type": "object",
                      "properties": {
                        "widthPt": {
                          "type": "number",
                          "exclusiveMinimum": 0
                        },
                        "heightPt": {
                          "type": "number",
                          "exclusiveMinimum": 0
                        },
                        "rotationDegrees": {
                          "type": "number"
                        },
                        "behindText": {
                          "type": "boolean"
                        },
                        "horizontal": {
                          "type": "object",
                          "properties": {
                            "relativeFrom": {
                              "enum": [
                                "page",
                                "margin"
                              ]
                            },
                            "alignment": {
                              "enum": [
                                "left",
                                "center",
                                "right"
                              ]
                            },
                            "offsetPt": {
                              "type": "number"
                            }
                          },
                          "additionalProperties": false,
                          "required": [
                            "relativeFrom"
                          ]
                        },
                        "vertical": {
                          "type": "object",
                          "properties": {
                            "relativeFrom": {
                              "enum": [
                                "page",
                                "margin"
                              ]
                            },
                            "alignment": {
                              "enum": [
                                "top",
                                "center",
                                "bottom"
                              ]
                            },
                            "offsetPt": {
                              "type": "number"
                            }
                          },
                          "additionalProperties": false,
                          "required": [
                            "relativeFrom"
                          ]
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "text"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "const": "picture"
                    },
                    "mediaPartPath": {
                      "type": "string"
                    },
                    "contentType": {
                      "type": "string"
                    },
                    "scalePercent": {
                      "enum": [
                        "auto",
                        50,
                        100,
                        150,
                        200,
                        500
                      ]
                    },
                    "widthPt": {
                      "type": "number",
                      "exclusiveMinimum": 0
                    },
                    "heightPt": {
                      "type": "number",
                      "exclusiveMinimum": 0
                    },
                    "lockAspectRatio": {
                      "type": "boolean"
                    },
                    "washout": {
                      "type": "boolean"
                    },
                    "opacity": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "placement": {
                      "type": "object",
                      "properties": {
                        "widthPt": {
                          "type": "number",
                          "exclusiveMinimum": 0
                        },
                        "heightPt": {
                          "type": "number",
                          "exclusiveMinimum": 0
                        },
                        "rotationDegrees": {
                          "type": "number"
                        },
                        "behindText": {
                          "type": "boolean"
                        },
                        "horizontal": {
                          "type": "object",
                          "properties": {
                            "relativeFrom": {
                              "enum": [
                                "page",
                                "margin"
                              ]
                            },
                            "alignment": {
                              "enum": [
                                "left",
                                "center",
                                "right"
                              ]
                            },
                            "offsetPt": {
                              "type": "number"
                            }
                          },
                          "additionalProperties": false,
                          "required": [
                            "relativeFrom"
                          ]
                        },
                        "vertical": {
                          "type": "object",
                          "properties": {
                            "relativeFrom": {
                              "enum": [
                                "page",
                                "margin"
                              ]
                            },
                            "alignment": {
                              "enum": [
                                "top",
                                "center",
                                "bottom"
                              ]
                            },
                            "offsetPt": {
                              "type": "number"
                            }
                          },
                          "additionalProperties": false,
                          "required": [
                            "relativeFrom"
                          ]
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "mediaPartPath",
                    "contentType",
                    "scalePercent",
                    "widthPt",
                    "heightPt",
                    "lockAspectRatio",
                    "washout",
                    "opacity",
                    "placement"
                  ]
                }
              ]
            }
          },
          "additionalProperties": false,
          "required": [
            "watermarkId",
            "owner",
            "effectiveIn",
            "watermark"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "success",
        "watermark"
      ]
    },
    {
      "type": "object",
      "properties": {
        "success": {
          "const": false
        },
        "failure": {
          "type": "object",
          "properties": {
            "code": {
              "enum": [
                "TARGET_NOT_FOUND",
                "PRECONDITION_FAILED"
              ]
            },
            "message": {
              "type": "string"
            },
            "details": {}
          },
          "additionalProperties": false,
          "required": [
            "code",
            "message"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "success",
        "failure"
      ]
    }
  ]
}
```

## Pre-apply throws

- `INVALID_INPUT`
- `INVALID_TARGET`
- `CAPABILITY_UNAVAILABLE`
- `INTERNAL_ERROR`

## Non-applied receipt codes

- `TARGET_NOT_FOUND`
- `PRECONDITION_FAILED`